Document contract-first usage and example

.ai/templates/user-story.md

@@ -34,6 +34,20 @@ Proposed | Ready | In Progress | Done (Sprint N) | Deferred
 
 ## Test Ideas
 
+## Example
+
+As a user, I want to export a territory, so that I can download the generated files.
+
+Contract example:
+
+- **Preconditions:** The territory exists and the user is authorized.
+- **Inputs:** Territory ID.
+- **Outputs:** A downloadable ZIP file.
+- **Postconditions:** The ZIP contains the generated XLSX and PDFs.
+- **Invariants:** The exported files are named consistently.
+- **Failure modes:** Missing territory, file write failure, or export timeout.
+- **Side effects:** Temporary export files may be created and cleaned up after download.
+
 ---
 
 ## Self-Evolution Protocol

README.md

@@ -32,6 +32,38 @@ Tell your AI coding agent:
 Read ./.ai/AGENTS.md and help me work as the Product Owner.
 ```
 
+## How to Use the Contract-First Workflow
+
+When you start a new feature or change:
+
+1. Ask the agent to write the user story.
+2. Require a contract before implementation.
+3. Review the contract for:
+   - Preconditions
+   - Inputs and outputs
+   - Postconditions
+   - Invariants
+   - Failure modes
+   - Side effects
+4. Turn the contract into acceptance criteria and tests.
+5. Implement only after the contract is clear.
+6. Re-check the result against the contract before accepting it.
+
+### Short Example
+
+```text
+As a user, I want to export a territory, so that I can download the generated files.
+
+Contract:
+- Preconditions: The territory exists and the user is authorized.
+- Inputs: Territory ID.
+- Outputs: A downloadable ZIP file.
+- Postconditions: The ZIP contains the generated XLSX and PDFs.
+- Invariants: The exported files are named consistently.
+- Failure modes: Missing territory, file write failure, or export timeout.
+- Side effects: Temporary export files may be created and cleaned up after download.
+```
+
 ## Intended Workflow
 
 Use this repo as the shared AI operating system, then let each downstream project keep its own product state and delivery history.