Proposals & Changes

The change proposal system lets you stage specification changes in isolation, get full compilation and review feedback, and then apply or archive them. Proposals live in .prodara/changes/ and follow a structured lifecycle.

Creating a Proposal

Use the /prodara prompt or the CLI to create a new proposal. Each proposal gets a timestamped directory with a delta.prd file for your specification changes and a metadata.json with status tracking. 

# Via AI prompt (in your AI agent)
/Prodara Create a proposal to add payment processing to billing module

# Via CLI
prodara propose "Add payment processing to billing module"

Directory Layout

project structure
.prodara/
  changes/
    2024-01-15T10-30-00-add-payments/
      delta.prd          # Specification changes
      metadata.json      # Status, author, timestamps
      design.md          # Optional design document
    archive/
      2024-01-10T09-00-00-add-users/
        delta.prd
        metadata.json

Proposal Lifecycle

1

draft

Created with prodara propose. The delta.prd file is ready for editing.

2

open

Submitted for review. The compiler validates the delta against the current graph.

3

approved

All reviewers have approved. Ready to apply.

4

applied

The delta has been merged into the main specification.

5

rejected

The proposal was rejected and moved to the archive.

6

archived

Manually archived without applying. Preserved for reference.

Metadata

Each proposal stores metadata alongside the delta spec:

metadata.json
{
  "id": "2024-01-15T10-30-00-add-payments",
  "description": "Add payment processing to billing module",
  "status": "open",
  "author": "agent",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:45:00Z"
}

Programmatic API

The proposal system is fully accessible via the compiler API: 

import {
  createProposal,
  listProposals,
  getProposal,
  applyProposal,
  archiveProposal,
} from '@prodara/compiler';

// Create a new proposal
const proposal = await createProposal(rootDir, 'Add payments');

// List all proposals
const all = await listProposals(rootDir);

// Apply an approved proposal
await applyProposal(rootDir, proposal.id);

// Archive without applying
await archiveProposal(rootDir, proposal.id);
ℹ️
Applied proposals are moved to .prodara/changes/archive/ so you can review them later. Use archiveProposal() to manually archive a proposal without applying it.

Next Steps

See Reviewers & Constitution to learn how proposals are reviewed, or Custom Workflows to integrate proposals into automated pipelines.