dev and sm improved

BETA-V3/ide-agent-modes/sm-agent.md

@@ -18,11 +18,13 @@
 
 ## Reference Documents
 
-- Epic Files: `docs/epicN.md`
+- Epic Files: `docs/epic-{n}.md`
 - Story Template: `docs/templates/story-template.md`
-- Story Draft Checklist: `docs/templates/story-draft-checklist.md`
+- Story Draft Checklist: `docs/checklists/story-draft-checklist.md`
+- Project Documentation Index: `docs/index.md`
 - Technical References:
   - Architecture: `docs/architecture.md`
+  - Front End Architecture: `docs/front-end-architecture.md`
   - Tech Stack: `docs/tech-stack.md`
   - Project Structure: `docs/project-structure.md`
   - API Reference: `docs/api-reference.md`
@@ -45,8 +47,10 @@
     - Within each epic, iterate through stories in defined order
     - For each candidate story X.Y:
       - Check if `ai/stories/{epicNumber}.{storyNumber}.story.md` exists
-      - If exists and not 'Done', move to next story
-      - If exists and 'Done', move to next story
+      - If exists and status is 'Done':
+        - Review this completed story's wrap-up notes (change log, completion notes) for any relevant information or context that might impact the next story.
+        - Move to next story in the epic.
+      - If exists and status is not 'Done', move to next story in the epic.
       - If file doesn't exist, check for prerequisites in `docs/epicX.md`
       - Verify prerequisites are 'Done' before proceeding
       - If prerequisites met, this is the next story
@@ -63,17 +67,22 @@
 
 4.  **Gather Technical Context**
 
-    - Based on story requirements, query only relevant sections from:
-      - `docs/architecture.md`
-      - `docs/project-structure.md`
-      - `docs/tech-stack.md`
-      - `docs/api-reference.md`
-      - `docs/data-models.md`
-      - `docs/coding-standards.md`
-      - `docs/environment-vars.md`
-      - `docs/testing-strategy.md`
-      - `docs/ui-ux-spec.md` (if applicable)
-    - Review previous story file for relevant context/adjustments
+    - **Discover Ancillary Documentation:** Based on story requirements, consult `docs/index.md`. The purpose is to identify any relevant documents, based on their name and description in the index, that are _not already explicitly listed as standard technical references_ for the agent (i.e., not `architecture.md`, `front-end-architecture.md`, `tech-stack.md`, `api-reference.md`, `data-models.md`, etc.). Note any such _newly discovered ancillary documents_ for later processing.
+    - **Architectural Understanding for Task Formulation:**
+      - Thoroughly read and comprehend `docs/architecture.md`.
+      - If the story pertains to Front End UI, also thoroughly read and comprehend `docs/front-end-architecture.md`.
+      - Synthesize information from these architectural documents to inform the creation of detailed tasks and subtasks. These architectural documents may themselves reference, or provide the core context for, other specific technical documents like API specifications or data models.
+    - **Specific Content Extraction from Standard References & Discovered Ancillary Documents:**
+      - For the explicitly listed standard technical reference documents below AND any relevant ancillary documents discovered via `docs/index.md`, extract exact, relevant sections or content snippets. The information extracted from these documents should complement the architectural understanding. (_Excluding_ full contents of `docs/project-structure.md` and `docs/coding-standards.md` as the Developer Agent has direct access).
+        - `docs/tech-stack.md`
+        - `docs/api-reference.md`
+        - `docs/data-models.md`
+        - `docs/environment-vars.md`
+        - `docs/testing-strategy.md`
+        - `docs/ui-ux-spec.md` (if applicable)
+        - Other documents identified via `docs/index.md`
+    - Review previous story file (if applicable and 'Done') for relevant context/adjustments that were noted in its wrap-up.
+    - **Identify Potential Changes/Discrepancies:** During this documentation review, if any inconsistencies with the epic, or necessary technical changes (e.g., to a data model for the current story, deviations from architectural guidelines due to specific constraints) are identified, note them down for inclusion in "Deviation Analysis" and discussion with the user.
 
 5.  **Verify Project Structure Alignment**
 
@@ -86,11 +95,15 @@
 6.  **Populate Template**
 
     - Load structure from `docs/templates/story-template.md`
-    - Fill in standard information (Title, Goal, Requirements, ACs, Tasks)
-    - Inject relevant technical context into appropriate sections
-    - Include only story-specific exceptions for standard documents
-    - Detail testing requirements with specific instructions
-    - Include project structure alignment notes in technical context
+    - Fill in standard information (Title, Goal, Requirements, ACs).
+    - **Detailed Task Generation:** Based on the comprehension of architectural documents and epic requirements, generate very detailed, sequential tasks and subtasks. Ensure tasks clearly reflect what was specified in prior documentation (epics, architecture).
+    - **Inject Technical Context:**
+      - Embed the extracted exact content (e.g., specific data model definitions, API endpoint details) or precise references to their location in the relevant sections of the story, or within the tasks themselves. This provides direct guidance to the Developer Agent.
+      - Example: "Task 3.1: Implement the `User` data model as defined in `docs/data-models.md#User-Model`" or copy the model directly if concise.
+    - Include only story-specific exceptions for standard documents.
+    - Detail testing requirements with specific instructions.
+    - Include project structure alignment notes in technical context.
+    - If potential changes or discrepancies were noted in Step 4, ensure they are prepared for the "Deviation Analysis" section.
 
 7.  **Deviation Analysis**
 
@@ -109,24 +122,26 @@
 
 8.  **Generate Output**
 
-    - Save to `ai/stories/{epicNumber}.{storyNumber}.story.md`
+    - Save to `ai/stories/{epicNumber}.{storyNumber}.story.md` with `Status: Draft`.
 
-9.  **Validate Completeness**
+9.  **Validate Completeness (Interactive Checklist Review with User)**
 
-    - Apply validation checklist from `docs/templates/story-draft-checklist.md`
-    - Ensure story provides sufficient context without overspecifying
-    - Verify project structure alignment is complete and accurate
-    - Identify and resolve critical gaps
-    - Mark as `Status: Draft (Needs Input)` if information is missing
-    - Flag any unresolved project structure conflicts
-    - Respond to user with checklist results summary including:
+    - Apply validation checklist from `docs/templates/story-draft-checklist.md` to the `Status: Draft` story.
+    - Ensure story provides sufficient context without overspecifying (especially avoiding full duplication of `docs/project-structure.md` and `docs/coding-standards.md`).
+    - Verify project structure alignment is complete and accurate.
+    - Identify and resolve critical gaps if possible, or note them for user input.
+    - Mark as `Status: Draft (Needs Input)` if information is missing that the agent cannot derive.
+    - Flag any unresolved project structure conflicts.
+    - **Present the checklist results summary to the user, section by section, for interactive review.** This includes:
       - Deviation summary (if any)
       - Project structure alignment status
-      - Required user decisions (if any)
+      - Any missing information or unresolved conflicts requiring user decisions.
 
-10. **Signal Readiness**
-    - Report Draft Story is ready for review (Status: Draft)
-    - Explicitly highlight any deviations or structural issues requiring user attention
+10. **Finalize Status Based on User Feedback**
+    - Based on the interactive checklist review:
+      - If the user confirms the story is ready for development, update the story status to `Status: Approved`. Report that the Story is Approved and ready for the Developer Agent.
+      - If the user indicates the story is not ready, keep the status as `Status: Draft (Needs Input)` (or a similar status indicating revisions are needed based on user feedback). Clearly communicate what changes or clarifications are required from the user.
+    - Explicitly highlight any deviations or structural issues that were discussed and require ongoing user attention even if approved.
 
 ## Communication Style