Add contract-first guidance to AI workflows

.ai/AGENTS.md

@@ -102,14 +102,21 @@ These files are for transient notes and local experimentation and should not nor
 
 1. Do not jump straight to code when requirements are unclear.
 2. Convert ideas into user stories and acceptance criteria.
-3. Prefer small vertical slices over large risky rewrites.
-4. Make assumptions explicit and ask the Product Owner when uncertainty matters.
-5. Keep outputs concise but complete.
-6. Use checklists before declaring work complete.
-7. Document important decisions as ADRs.
-8. Propose improvements when lessons are learned.
-9. Never silently change project standards.
-10. Preserve project-specific conventions.
+3. Define the design-by-contract boundary before implementation:
+   - Preconditions
+   - Inputs and outputs
+   - Postconditions
+   - Invariants
+   - Failure modes
+   - Side effects
+4. Prefer small vertical slices over large risky rewrites.
+5. Make assumptions explicit and ask the Product Owner when uncertainty matters.
+6. Keep outputs concise but complete.
+7. Use checklists before declaring work complete.
+8. Document important decisions as ADRs.
+9. Propose improvements when lessons are learned.
+10. Never silently change project standards.
+11. Preserve project-specific conventions.
 
 ## Agent Routing
 
@@ -174,6 +181,7 @@ A story is ready when it has:
 
 - Clear user value
 - User story format
+- Contract-first inputs, outputs, invariants, and failure modes
 - Acceptance criteria
 - Known constraints
 - Dependencies identified
@@ -185,6 +193,7 @@ A story is ready when it has:
 A story is done when:
 
 - Acceptance criteria pass
+- The implemented behavior matches the documented contract
 - Code is reviewed
 - Tests are created or updated
 - Security concerns are checked

.ai/SKILLS.md

@@ -13,6 +13,7 @@ Agents should not load every skill for every task. Load only what is needed.
 - Secure defaults
 - Testable outputs
 - Maintainable structure
+- Explicit contracts for inputs, outputs, invariants, and failure modes
 - Product Owner alignment
 - Agile delivery
 - Concise documentation
@@ -24,6 +25,7 @@ Agents should not load every skill for every task. Load only what is needed.
 | Agile delivery | `./skills/agile.md` |
 | Scrum events | `./skills/scrum.md` |
 | Architecture | `./skills/architecture.md` |
+| Design by contract | `./skills/design-by-contract.md` |
 | Clean code | `./skills/clean-code.md` |
 | Testing | `./skills/testing.md` |
 | Security | `./skills/security.md` |

.ai/skills/architecture.md

@@ -7,6 +7,7 @@ Design maintainable systems using clear boundaries, tradeoff analysis, and ADRs.
 ## Principles
 
 - Prefer clarity over cleverness.
+- Prefer explicit contracts over implied behavior.
 - Keep instructions short and routable.
 - Use examples where they prevent mistakes.
 - Avoid duplicating rules that belong in another file.
@@ -29,6 +30,7 @@ Design maintainable systems using clear boundaries, tradeoff analysis, and ADRs.
 - Use checklists for repeatable work.
 - Use tables for routing and decisions.
 - Keep examples minimal and practical.
+- Capture preconditions, postconditions, invariants, and failure modes when defining behavior.
 - Store project-specific facts in project files.
 - Store reusable rules in skill files.
 - Store role behavior in agent files.

.ai/skills/clean-code.md

@@ -7,6 +7,7 @@ Write simple, readable, testable, maintainable code.
 ## Principles
 
 - Prefer clarity over cleverness.
+- Prefer explicit contracts over implied behavior.
 - Keep instructions short and routable.
 - Use examples where they prevent mistakes.
 - Avoid duplicating rules that belong in another file.
@@ -29,6 +30,7 @@ Write simple, readable, testable, maintainable code.
 - Use checklists for repeatable work.
 - Use tables for routing and decisions.
 - Keep examples minimal and practical.
+- Capture preconditions, postconditions, invariants, and failure modes when behavior matters.
 - Store project-specific facts in project files.
 - Store reusable rules in skill files.
 - Store role behavior in agent files.

.ai/skills/design-by-contract.md

@@ -0,0 +1,111 @@
+# Skill — Design by Contract
+
+## Purpose
+
+Create work with explicit preconditions, postconditions, invariants, and failure modes so agents and humans can reason about behavior before implementation.
+
+## Principles
+
+- Prefer explicit contracts over implied behavior.
+- Make inputs, outputs, side effects, and errors visible.
+- Define the boundaries before writing code.
+- Keep contracts short enough to scan and test.
+- Treat contract violations as bugs, not surprises.
+- Align tests, documentation, and implementation to the same contract.
+- Treat the Product Owner as the final authority.
+
+## Process
+
+1. Identify the callable boundary, user action, or document being created.
+2. Write the contract:
+   - Preconditions
+   - Inputs and types
+   - Outputs and success criteria
+   - Postconditions
+   - Invariants
+   - Failure modes
+   - Side effects
+3. Check whether any assumption is unstated or ambiguous.
+4. Convert the contract into acceptance criteria or checks.
+5. Implement or document only after the contract is clear.
+6. Validate the result against the contract.
+
+## Best Practices
+
+- Use numbered or bulleted contracts for quick review.
+- State what must be true before work starts.
+- State what must be true when work finishes.
+- Call out any data ownership or persistence expectations.
+- Include error handling and retry expectations when relevant.
+- Prefer contract tests for public interfaces and workflows.
+- Record contract changes in the relevant documentation or story.
+
+## Contract Checklist
+
+- [ ] Preconditions are stated.
+- [ ] Inputs are named and bounded.
+- [ ] Outputs or deliverables are defined.
+- [ ] Invariants are clear.
+- [ ] Failure modes are described.
+- [ ] Side effects are explicit.
+- [ ] Tests or validation steps map to the contract.
+- [ ] The Product Owner can review the result without guessing.
+
+## Anti-Patterns
+
+- Hidden assumptions.
+- “It should just work” requirements.
+- Implementing before the boundary is clear.
+- Testing behaviors no one asked for.
+- Documentation that does not match the implementation.
+
+## Output Standard
+
+Outputs should be:
+
+- Complete enough to implement against
+- Concise enough to review quickly
+- Structured in Markdown
+- Easy to turn into tests
+- Easy to update when the contract changes
+
+---
+
+## Self-Evolution Protocol
+
+This file is allowed to improve over time, but only through a controlled change process.
+
+### When to propose an update
+
+An agent may propose an update when it learns:
+
+- A recurring mistake should be prevented.
+- A better workflow has been proven useful.
+- A project-specific convention has become stable.
+- A prompt pattern produced better results.
+- A tool, framework, library, or deployment rule changed.
+- The Product Owner approved a new standard.
+
+### How to update this file
+
+Agents must not silently rewrite this file. They must create an improvement proposal using:
+
+`./.ai/evolution/improvement-proposal-template.md`
+
+Every proposal must include:
+
+- File to update
+- Current problem
+- Proposed change
+- Reason
+- Risk
+- Rollback plan
+- Product Owner approval status
+
+### Learning Log
+
+Add durable lessons here only after they are proven useful.
+
+| Date | Lesson Learned | Change Made | Approved By |
+|---|---|---|---|
+| YYYY-MM-DD | Initial baseline created. | Created file. | Product Owner |

.ai/skills/documentation.md

@@ -7,6 +7,7 @@ Create concise docs that help developers, users, and maintainers act quickly.
 ## Principles
 
 - Prefer clarity over cleverness.
+- Prefer explicit contracts over implied behavior.
 - Keep instructions short and routable.
 - Use examples where they prevent mistakes.
 - Avoid duplicating rules that belong in another file.
@@ -29,6 +30,8 @@ Create concise docs that help developers, users, and maintainers act quickly.
 - Use checklists for repeatable work.
 - Use tables for routing and decisions.
 - Keep examples minimal and practical.
+- Document preconditions, postconditions, invariants, and failure modes in the same artifact when possible.
+- Make the contract visible before implementation notes.
 - Store project-specific facts in project files.
 - Store reusable rules in skill files.
 - Store role behavior in agent files.

.ai/skills/testing.md

@@ -7,6 +7,7 @@ Plan and create unit, integration, regression, acceptance, and exploratory tests
 ## Principles
 
 - Prefer clarity over cleverness.
+- Prefer contract-driven tests over guesswork.
 - Keep instructions short and routable.
 - Use examples where they prevent mistakes.
 - Avoid duplicating rules that belong in another file.
@@ -29,6 +30,8 @@ Plan and create unit, integration, regression, acceptance, and exploratory tests
 - Use checklists for repeatable work.
 - Use tables for routing and decisions.
 - Keep examples minimal and practical.
+- Derive test cases from preconditions, postconditions, invariants, and failure modes.
+- Add at least one test or validation step for each contract boundary when practical.
 - Store project-specific facts in project files.
 - Store reusable rules in skill files.
 - Store role behavior in agent files.

.ai/templates/test-plan.md

@@ -4,6 +4,16 @@
 
 ## Scope
 
+## Contract Under Test
+
+- Preconditions:
+- Inputs:
+- Outputs:
+- Postconditions:
+- Invariants:
+- Failure modes:
+- Side effects:
+
 ## Test Types
 
 ## Test Cases
@@ -12,6 +22,10 @@
 
 ## Acceptance Validation
 
+- [ ] Contract boundaries are verified.
+- [ ] Failure modes are covered.
+- [ ] Postconditions are observable.
+
 ---
 
 ## Self-Evolution Protocol

.ai/templates/user-story.md

@@ -9,6 +9,16 @@ As a [user], I want [capability], so that [benefit].
 - [ ] Criteria 1
 - [ ] Criteria 2
 
+## Contract
+
+- **Preconditions:**
+- **Inputs:**
+- **Outputs:**
+- **Postconditions:**
+- **Invariants:**
+- **Failure modes:**
+- **Side effects:**
+
 ## Status
 
 Proposed | Ready | In Progress | Done (Sprint N) | Deferred

.ai/workflows/new-feature.md

@@ -15,16 +15,24 @@ From idea to accepted feature.
 1. Restate the goal.
 2. Identify the primary agent.
 3. Load needed skills.
-4. Define the expected output.
-5. Break work into small steps.
-6. Produce the result.
-7. Validate against the relevant checklist.
-8. Record important decisions.
-9. Propose file evolution when a durable lesson was learned.
+4. Define the contract first:
+   - Preconditions
+   - Inputs and outputs
+   - Postconditions
+   - Invariants
+   - Failure modes
+   - Side effects
+5. Define the expected output.
+6. Break work into small steps.
+7. Produce the result.
+8. Validate against the relevant checklist and contract.
+9. Record important decisions.
+10. Propose file evolution when a durable lesson was learned.
 
 ## Outputs
 
 - Markdown summary
+- Contract or contract notes, when relevant
 - Decisions
 - Risks
 - Tasks

README.md

@@ -38,9 +38,9 @@ Use this repo as the shared AI operating system, then let each downstream projec
 
 1. Start the agent with `./.ai/AGENTS.md`.
 2. Define or refine the project in `./.ai/project/`.
-3. Ask the agent to turn ideas into epics, stories, and acceptance criteria before coding.
+3. Ask the agent to turn ideas into epics, stories, acceptance criteria, and a design-by-contract boundary before coding.
 4. Implement work in small vertical slices.
-5. Review results against acceptance criteria, tests, security, and documentation.
+5. Review results against the contract, acceptance criteria, tests, security, and documentation.
 6. Capture durable lessons in `./.ai/evolution/proposals/` before changing reusable rules.
 7. Promote approved `upstream-candidate` improvements back into this boilerplate repo.
 
@@ -105,7 +105,7 @@ Based on the current vision, create a first roadmap and a starter backlog with e
 ### Story refinement
 
 ```text
-Take this feature idea and convert it into a user story with acceptance criteria, constraints, dependencies, and a test approach. Ask me questions before proceeding if anything important is missing.
+Take this feature idea and convert it into a user story with acceptance criteria, constraints, dependencies, a design-by-contract boundary, and a test approach. Ask me questions before proceeding if anything important is missing.
 ```
 
 ```text
@@ -119,7 +119,7 @@ Act as the software architect and backend lead. Propose the smallest safe implem
 ```
 
 ```text
-Implement this story as a small vertical slice. Update code, tests, and documentation. If you are unsure about behavior or requirements, stop and ask me instead of guessing.
+Implement this story as a small vertical slice. Update code, tests, and documentation. Define the contract first and stop to ask me if any behavior or requirement is unclear instead of guessing.
 ```
 
 ### Review