Writing contracts

Three ways to create a devcontract.json: start from an archetype, write from scratch, or let Stack mode generate one from your project settings. Choose the approach that fits your situation.

Option 1: Start from an archetype (recommended)

The fastest path. Pick the archetype closest to your engagement type, copy it, and edit the fields that differ.

1. Review the three archetypes and choose the closest match.
2. Copy the JSON to .tickety/devcontract.json in your project root.
3. Edit project and parties.client to your values.
4. Adjust stack.region, cost.forbidden_resources, and compliance.frameworks to match your actual constraints.
5. Remove the _comment field.
6. Open tickety-ai. The contract block will appear at the top of the next session's system prompt.

Option 2: Write by hand

If none of the archetypes fit, write the contract from scratch. Required clauses are: stack, cost, security, and definition_of_done. All others are optional.

Start with this minimal skeleton and add clauses as needed:

{
  "contract_version": "1.0",
  "project": "your-project",
  "parties": {
    "client": "your-name",
    "contractor": "claude-code"
  },
  "stack": {
    "language": "python",
    "language_version": "3.12",
    "runtime": "aws_lambda",
    "region": "eu-north-1"
  },
  "cost": {
    "budget_envelope": "aws_free_tier"
  },
  "security": {
    "auth_mechanism": "cognito_jwt",
    "secrets_store": "ssm_parameter_store"
  },
  "definition_of_done": {
    "tests_pass": true,
    "no_contract_violations": true,
    "scan_gates": []
  }
}

Then add the optional clauses that apply: architecture if you have specific pattern requirements, quality to set coverage and logging standards, compliance for regulatory frameworks, and audit for evidence requirements.

Option 3: Generate from Stack mode

If you have tickety-ai installed, Stack mode reads your project settings and generates a contract stub. Open the tickety-ai side panel, switch to Stack mode, and select Generate DevContract. Stack mode reads your .tickety/steering/ files and your existing project structure to infer sensible defaults.

The generated stub always needs human review — Stack mode cannot infer your compliance requirements or cost envelope from code alone. Treat the output as a starting point, not a finished contract.

Where to place the file

The contract must be at .tickety/devcontract.json in your project root. tickety-ai looks for it at this exact path. If the file does not exist, the session starts with steering files only (no contract).

your-project/
├── .tickety/
│   ├── devcontract.json    ← here
│   └── steering/
│       └── stack.md
├── src/
└── ...

Validating your contract

The Python schema in demos/ticketyboo/api/contract_schema.py can validate any contract file:

from contract_schema import load_contract

contract = load_contract(".tickety/devcontract.json")
print(f"Contract hash: {contract.contract_hash()}")

load_contract() raises ValueError with a descriptive message if the file is malformed or missing required fields. Use this in your CI pipeline to catch contract errors before they affect a session.

Versioning your contract

Commit .tickety/devcontract.json to version control. Every evidence bundle is signed against the contract hash — if the contract changes between sessions, the evidence bundles will have different hashes, creating a clear audit trail of when contract terms changed.

For enterprise engagements, treat contract changes the same way you treat specification changes: they require review and approval, and the new version should be committed with a clear commit message explaining what changed and why.