Spec Lifecycle

Why specs have a lifecycle

Specifications are the most important artifacts in Contextia. They define what components do, how subsystems behave, and what contracts code must satisfy. Because specs govern implementation, changes to them must be deliberate, reviewed, and traceable.

Without a lifecycle, specs would be static documents that are either present or absent. In practice, specifications evolve: they start as drafts during initial design, become current when the implementation is accepted, and are eventually deprecated when the feature they describe is replaced or removed. Contextia models this evolution explicitly through status fields and a staging workflow.

Status values

Every spec has a status field in its YAML frontmatter. There are three valid statuses:

---
type: spec
id: SPEC-AUTH-001
title: Authentication and Authorization
status: current  # draft | current | deprecated
---

draft

A spec in draft status is a work in progress. It describes intended behavior that has not yet been fully implemented or reviewed. Draft specs are included in context assembly but are clearly marked so the agent knows the specification is not yet authoritative.

status: draft

Draft specs are appropriate when:

• A feature is being designed but not yet implemented
• A spec has been proposed but not yet reviewed
• An existing spec is being rewritten (the new version starts as a draft)

Note

AI agents should treat draft specs as guidance, not as hard constraints. If a draft spec conflicts with existing behavior, the agent should flag the conflict rather than silently following the draft.

current

A spec in current status is the authoritative contract. It describes behavior that is implemented, reviewed, and expected to hold. When an agent loads context for a task, current specs are the primary source of truth.

status: current

The transition from draft to current happens when:

• The implementation matches the spec
• The spec has been reviewed by the team
• The spec is promoted from a proposal (see staging workflow below)

Most specs in a healthy project are current. This is the steady state.

deprecated

A spec in deprecated status describes behavior that is being phased out. The code it governs may still exist, but the specification is no longer authoritative for new work.

status: deprecated
deprecated_by: SPEC-AUTH-002  # optional: the replacement spec
deprecated_date: 2026-02-15

Deprecated specs remain in the system layer — they are not deleted. This preserves history and allows agents to understand why old code was written the way it was. When an agent encounters a deprecated spec in context, it knows not to follow its patterns for new code.

Tip

When deprecating a spec, always set deprecated_by if a replacement exists. This creates a forward pointer that agents and developers can follow to find the current specification.

The lifecycle in practice

         ┌──────────┐
         │  draft    │  New spec being designed
         └────┬─────┘
              │ review + implement
              v
         ┌──────────┐
         │  current  │  Authoritative contract
         └────┬─────┘
              │ replaced or removed
              v
         ┌──────────┐
         │deprecated │  Phased out, kept for history
         └──────────┘

Creating a new spec

New specs are created with contextia new spec:

contextia new spec --id SPEC-PAYMENTS-001 --title "Payment Processing"

This generates a spec file from the template with status: draft:

---
type: spec
id: SPEC-PAYMENTS-001
title: Payment Processing
status: draft
links:
  decisions: []
  norms: []
paths: []
tags: []
created: 2026-03-02
---

# Payment Processing

<!-- Describe the behavioral contract for this component -->

The developer (or agent, via the staging workflow) fills in the spec body, links, and paths. When it is ready for review, it stays as draft until explicitly promoted.

Promoting to current

When a draft spec has been implemented and reviewed:

contextia spec set-status SPEC-PAYMENTS-001 current

This updates the frontmatter in place. The spec is now authoritative — agents will treat it as a hard constraint in future tasks.

Deprecating a spec

When a spec is replaced:

contextia spec deprecate SPEC-AUTH-001 --replaced-by SPEC-AUTH-002

This sets status: deprecated, adds deprecated_by: SPEC-AUTH-002, and records the date. The old spec remains accessible for reference.

The staging workflow

The lifecycle described above works well for human-authored specs. But what happens when an AI agent needs to modify a specification? This is a common scenario: the agent is implementing a task that reveals the spec needs updating — perhaps a new field was added, an edge case was discovered, or a subsystem’s behavior changed.

Allowing the agent to edit specs directly would be dangerous. Specs are durable system knowledge that governs all future work. An incorrect spec change could cascade through the project, causing every subsequent agent interaction to follow wrong constraints.

Contextia solves this with a staging workflow: agents propose changes, humans review them, and an explicit command promotes accepted proposals.

How staging works

Step 1: Agent identifies need for spec change during task work

Step 2: Agent writes proposal to staging area
  → work/active/TASK-042/proposals/SPEC-BILLING-001-v2.md

Step 3: Human reviews proposal
  → Accept, reject, or modify

Step 4: Accepted proposal is promoted
  → contextia spec promote work/active/TASK-042/proposals/SPEC-BILLING-001-v2.md
  → Updates system/specs/SPEC-BILLING-001.md with the changes

Writing proposals

When an agent determines a spec change is needed, it uses the propose_spec_change MCP tool (or contextia spec propose CLI command). The proposal is a complete spec file — not a diff — placed in the task’s proposals directory:

---
type: spec
id: SPEC-BILLING-001
title: Invoice Generation
status: draft
version: 2
changelog:
  - version: 2
    date: 2026-03-02
    task: TASK-042
    summary: Added multi-currency support
    changes:
      - Added currency parameter to invoice generation
      - Added exchange rate fetching requirement
      - Updated tax calculation to be currency-aware
links:
  decisions: [DEC-BILLING-001, DEC-BILLING-003, DEC-CURRENCY-001]
  norms: [NORM-ERROR-001, NORM-ASYNC-001]
paths:
  - src/billing/invoice/**
  - src/billing/currency/**
  - src/billing/templates/invoice*
tags: [billing, invoicing, pdf, multi-currency]
---

# Invoice Generation

The invoice generation subsystem creates PDF invoices from
subscription and usage data at the end of each billing cycle.
Invoices support multiple currencies per customer account.

## Responsibilities

- Aggregate line items from usage records and plan charges
- **Resolve the customer's configured currency**
- **Fetch current exchange rates from the configured provider**
- Apply discounts, proration, and tax calculations
  **respecting currency-specific rounding rules**
- Render invoices to PDF using the configured template
- Store generated invoices in S3 with a 7-year retention policy
- Send invoice notifications via the notification subsystem

The proposal includes a changelog entry that records what changed, why, and which task motivated the change. This creates a traceable history of spec evolution.

The golden rule

Agents never modify files in system/specs/ directly. All spec changes go through work/active/{task}/proposals/ and require human promotion. This is a safety invariant that Contextia enforces.

Reviewing proposals

Proposals are regular Markdown files in a known location. The developer reviews them using whatever workflow they prefer — reading the file directly, using a diff tool, or running a comparison:

# Compare proposal against current spec
diff system/specs/SPEC-BILLING-001.md \
     work/active/TASK-042/proposals/SPEC-BILLING-001-v2.md

# Or view the proposal with contextia
contextia spec diff SPEC-BILLING-001 \
     work/active/TASK-042/proposals/SPEC-BILLING-001-v2.md

The developer may accept the proposal as-is, edit it before promotion, or reject it entirely.

Promoting proposals

When a proposal is accepted, promotion merges it into the system layer:

contextia spec promote \
    work/active/TASK-042/proposals/SPEC-BILLING-001-v2.md

This command:

1. Validates the proposal’s frontmatter (correct ID, valid links, proper changelog)
2. Replaces system/specs/SPEC-BILLING-001.md with the proposal content
3. Updates the status to current (proposals are always draft)
4. Removes the proposal file from the staging area
5. Records the promotion in the task’s session log

After promotion, the spec is authoritative. The next time an agent loads context that includes SPEC-BILLING-001, it gets the updated version.

Versioning and changelog

Specs evolve over time. The changelog field in frontmatter records this evolution:

changelog:
  - version: 3
    date: 2026-03-02
    task: TASK-042
    summary: Added multi-currency support
    changes:
      - Added currency parameter to invoice generation
      - Added exchange rate fetching requirement
  - version: 2
    date: 2025-11-20
    task: TASK-028
    summary: Added async invoice generation
    changes:
      - Invoice generation is now asynchronous
      - Added webhook notification on completion
  - version: 1
    date: 2025-08-14
    task: TASK-001
    summary: Initial specification
    changes:
      - Defined core invoice generation responsibilities

The changelog serves multiple purposes:

Traceability. Every change is linked to the task that motivated it. You can trace why the spec looks the way it does by following the task IDs.

Agent context. When an agent reads a spec’s changelog, it understands how the spec has evolved. If the agent’s task is related to a recent change, the changelog provides relevant history.

Review efficiency. During proposal review, the developer can see exactly what changed and why, without diffing the entire document.

Version numbering

Versions are simple integers, not semantic versions. Every promoted proposal increments the version by one. The version number has no semantic meaning beyond ordering — there is no concept of “breaking” vs. “non-breaking” spec changes.

version: 3  # Third promoted revision of this spec

Multiple proposals for the same spec

When multiple tasks are active simultaneously, they may both propose changes to the same spec. This is handled by the file naming convention:

work/active/TASK-042/proposals/SPEC-BILLING-001-v2.md
work/active/TASK-043/proposals/SPEC-BILLING-001-v2.md

Each task’s proposals directory is independent. If both proposals are accepted, they must be promoted sequentially:

# Promote TASK-042's proposal first
contextia spec promote work/active/TASK-042/proposals/SPEC-BILLING-001-v2.md

# Now TASK-043's proposal may need rebasing against the new version
# The developer reviews and potentially updates before promoting
contextia spec promote work/active/TASK-043/proposals/SPEC-BILLING-001-v3.md

This is analogous to merge conflicts in version control. Conflicting spec changes require human judgment to resolve, which is exactly the right behavior for durable system knowledge.

Integration with context assembly

The spec lifecycle affects how context assembly works:

Spec status	Included in context?	How it is presented
current	Always (when linked)	Presented as authoritative
draft	Yes (when linked)	Marked as draft, not yet authoritative
deprecated	Only if directly linked	Marked as deprecated, with forward pointer

When assembling context for a task, current specs are the primary focus. Draft specs provide forward-looking guidance. Deprecated specs are included only when the task explicitly references them, providing historical context for code that has not yet been migrated.

# Context assembly respects status
contextia context TASK-042

# Output clearly marks status:
# === SPEC: SPEC-BILLING-001 (current) ===
# ...
# === SPEC: SPEC-LEGACY-AUTH (deprecated → SPEC-AUTH-002) ===
# ...

Tip

When deprecating a spec, update any tasks that reference it to point to the replacement. This keeps context assembly clean and avoids agents receiving outdated specifications for active work.

Summary

The spec lifecycle and staging workflow together ensure that durable system knowledge is treated with the care it deserves:

1. Specs have explicit statuses (draft, current, deprecated) that affect how they are used in context
2. AI agents propose changes rather than editing specs directly
3. Humans review and promote proposals, maintaining control over durable knowledge
4. Changelogs record evolution with traceability back to the tasks that motivated changes
5. Version numbering provides clear ordering of spec revisions
6. Context assembly respects status, presenting specs appropriately based on their lifecycle stage

This workflow adds a review step to the AI development loop, but it is a deliberate trade-off: the cost of reviewing a spec proposal is far less than the cost of an incorrect specification propagating through future agent interactions.