Refactor code structure for improved readability and maintainability

.specify/templates/tasks-template.md

@@ -12,6 +12,8 @@ description: "Task list template for feature implementation"
 
 **Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
 
+**Self-Containment**: Tasks will be executed by a DIFFERENT model than the one generating them. The generating model has deep reasoning capability and can infer implementation details from sparse descriptions. The implementing model does NOT — it needs explicit, self-contained context embedded directly in each task. Every non-trivial task must include an indented **Context** block (see examples below).
+
 ## Format: `[ID] [P?] [Story] Description`
 
 - **[P]**: Can run in parallel (different files, no dependencies)
@@ -48,6 +50,11 @@ description: "Task list template for feature implementation"
 
 **Purpose**: Project initialization and basic structure
 
+**Phase Context**:
+- **Files modified in this phase**: `package.json` (project manifest), `src/` (directory structure), `.eslintrc` (linting config)
+- **Key types/interfaces used**: None yet — this phase creates the foundation
+- **Codebase conventions to follow**: [Reference project guidelines or existing patterns]
+
 - [ ] T001 Create project structure per implementation plan
 - [ ] T002 Initialize [language] project with [framework] dependencies
 - [ ] T003 [P] Configure linting and formatting tools
@@ -79,6 +86,11 @@ Examples of foundational tasks (adjust based on your project):
 
 **Independent Test**: [How to verify this story works on its own]
 
+**Phase Context**:
+- **Files modified in this phase**: [Full paths with one-line description of each file's current purpose]
+- **Key types/interfaces used**: [Quoted signatures of types that tasks in this phase depend on]
+- **Codebase conventions to follow**: [Naming patterns, error handling style, import grouping, test patterns — reference specific files as examples]
+
 ### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
 
 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
@@ -89,6 +101,14 @@ Examples of foundational tasks (adjust based on your project):
 ### Implementation for User Story 1
 
 - [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+
+  **Context**:
+  - **Existing code references**: [Quote the exact interface/base class this model must implement, with fenced code block]
+  - **Target file state**: `src/models/` directory exists after T001; no other models present yet
+  - **Expected implementation pattern**: [Show code skeleton or reference similar pattern in codebase, e.g., "Follow the same pattern as `BaseEntity` in `src/models/base.py` lines 10-45"]
+  - **Key decisions and gotchas**: [Non-obvious constraints from spec/research, e.g., "Must use UUID for primary key per spec NFR-3" or "Field `name` has max length 255 per data-model.md"]
+  - **Acceptance signal**: [Concrete verification, e.g., "`python -m pytest tests/unit/test_entity1.py` passes" or "File imports successfully with no errors"]
+
 - [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
 - [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
 - [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
@@ -249,3 +269,6 @@ With multiple developers:
 - Commit after each task or logical group
 - Stop at any checkpoint to validate story independently
 - Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
+- **Every non-trivial task MUST include an indented Context block** with: existing code references (quoted signatures), target file state, expected implementation pattern (code skeleton or analogous pattern reference), key decisions/gotchas, and a concrete acceptance signal
+- **Every phase MUST include a Phase Context summary** listing: files modified, key types/interfaces used, and codebase conventions to follow
+- Context blocks should source information from plan artifacts (contracts, data-model, research, quickstart) first, and only read source files when the plan references an existing pattern that needs to be matched