Added better docs to README.md

README.md

@@ -32,6 +32,116 @@ Tell your AI coding agent:
 Read ./.ai/AGENTS.md and help me work as the Product Owner.
 ```
 
+## Intended Workflow
+
+Use this repo as the shared AI operating system, then let each downstream project keep its own product state and delivery history.
+
+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.
+4. Implement work in small vertical slices.
+5. Review results against 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.
+
+## Typical Session Flow
+
+### 1. Project setup
+
+Use the agent to establish the project definition:
+
+- Fill in `vision.md`
+- Capture important decisions in `decisions.md`
+- Build a roadmap in `roadmap.md`
+- Turn priorities into epics and stories in `backlog.md`
+
+### 2. Feature planning
+
+Before implementation, ask the agent to clarify the request, identify missing information, and write acceptance criteria.
+
+The agent should ask you for clarification instead of guessing whenever requirements are missing or ambiguous.
+
+### 3. Implementation
+
+Once the story is ready, ask the appropriate agent to implement the smallest useful slice and update tests and docs.
+
+### 4. Review and release
+
+Ask the agent to review the work against Definition of Done, document decisions, and note release impact.
+
+### 5. Learning and promotion
+
+When the agent discovers a durable improvement:
+
+- Put temporary notes in `.ai/logs/` or `.ai/local/`
+- Create a proposal in `.ai/evolution/proposals/`
+- Mark it `project-only` or `upstream-candidate`
+- Promote only reusable lessons back into the boilerplate
+
+## Prompt Examples
+
+Use prompts like these to drive the workflow.
+
+### Startup
+
+```text
+Read ./.ai/AGENTS.md and help me work as the Product Owner. Start by reviewing ./.ai/project/vision.md and ./.ai/project/decisions.md.
+```
+
+```text
+Read ./.ai/AGENTS.md, ask clarifying questions when anything is unclear, and do not make up missing requirements.
+```
+
+### Product definition
+
+```text
+Help me turn this idea into a project vision, target users, main problems solved, and product principles. Update ./.ai/project/vision.md.
+```
+
+```text
+Based on the current vision, create a first roadmap and a starter backlog with epics and user stories.
+```
+
+### 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.
+```
+
+```text
+Review ./.ai/project/backlog.md and tell me which stories are not ready for implementation yet, and what clarification you need from me.
+```
+
+### Architecture and implementation
+
+```text
+Act as the software architect and backend lead. Propose the smallest safe implementation plan for this story, including risks, assumptions, and affected files.
+```
+
+```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.
+```
+
+### Review
+
+```text
+Review this change against the acceptance criteria, Definition of Done, and security concerns. Tell me what is missing or risky.
+```
+
+```text
+Summarize what changed, what still needs Product Owner clarification, and whether this is ready to accept.
+```
+
+### Evolution and upstream learning
+
+```text
+We learned something reusable from this project. Create an improvement proposal in ./.ai/evolution/proposals/ and classify it as project-only or upstream-candidate.
+```
+
+```text
+Review this lesson and tell me whether it belongs in project files, local notes, or the reusable boilerplate. Do not promote it upstream unless it clearly generalizes.
+```
+
 ## Key Features
 
 - Product Owner-centered delivery