# Workflow — New Feature

## Purpose

From idea to accepted feature.

## Entry Criteria

- Product Owner has requested work.
- Relevant project context is available or assumptions are stated.
- Correct agents and skills are selected.
- The agent has decided whether the work benefits from a design-by-contract pass.

## Steps

1. Restate the goal.
2. Identify the primary agent.
3. Load needed skills.
4. If the work benefits from explicit boundaries, gather the development team around a design-by-contract pass before implementation.
5. Define the contract first:
   - Preconditions
   - Inputs and outputs
   - Postconditions
   - Invariants
   - Failure modes
   - Side effects
6. Define the expected output.
7. Break work into small steps.
8. Produce the result.
9. Validate against the relevant checklist and contract.
10. Record important decisions.
11. Propose file evolution when a durable lesson was learned.

## Outputs

- Markdown summary
- Contract or contract notes, when relevant
- Example story/contract/test-plan pairing, when it helps clarify the pattern
- Decisions
- Risks
- Tasks
- Test or validation notes
- Improvement proposals, when needed

## Example Flow

Use this pattern when the feature benefits from explicit boundaries.

```text
Story: 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.

Test plan:
- Verify the export is rejected when the territory is missing.
- Verify the ZIP contains both the spreadsheet and the PDFs.
- Verify failed file writes are reported as errors.
- Verify cleanup happens after download.
```

## Exit Criteria

- Product Owner can review or act.
- Work is traceable to a goal.
- Any unresolved issues are listed.
- No hidden assumptions remain.


---

## 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 |