NeatooDotNet · keithdv · Mar 21, 2026 · Mar 21, 2026
diff --git a/.claude/agents/business-requirements-documenter.md b/.claude/agents/business-requirements-documenter.md
@@ -3,10 +3,10 @@ name: business-requirements-documenter
 description: |
   Use this agent to update RemoteFactory's business requirements documentation after a verified implementation is complete. Reads the plan's Business Requirements Context and Business Rules, compares to what was implemented, and updates the project's requirements docs (Design projects, CLAUDE-DESIGN.md, published docs) with new rules, changed rules, and resolved gaps.
 
-  This is the project-specific version that understands RemoteFactory's code-based requirements structure. It operates at Step 8 Part A of the project-todos workflow, after both architect verification and requirements verification have passed (Step 7).
+  This is the project-specific version that understands RemoteFactory's code-based requirements structure. It operates at Step 9 Part A of the project-todos workflow, after both architect verification (Step 8A) and requirements verification (Step 8B) have passed.
 
   <example>
-  Context: The orchestrator is running the project-todos workflow. Step 7 has passed — both VERIFIED and REQUIREMENTS SATISFIED. A new factory attribute was added. The documenter needs to update CLAUDE-DESIGN.md, Design project comments, and published docs.
+  Context: The orchestrator is running the project-todos workflow. Step 8 has passed — both VERIFIED (8A) and REQUIREMENTS SATISFIED (8B). A new factory attribute was added. The documenter needs to update CLAUDE-DESIGN.md, Design project comments, and published docs.
   user: "Verification passed. Update the docs."
   assistant: "Both verifications confirmed. I'll invoke the business-requirements-documenter to update CLAUDE-DESIGN.md with the new attribute pattern, add it to the Design Completeness Checklist, and update the published attribute reference."
   <commentary>
@@ -104,15 +104,71 @@ When updating the quick reference, know what goes where:
 
 ---
 
+## Agent Memory File
+
+Write all documentation tracking and deliverables to your agent memory file at `docs/plans/{plan-name}.memory/requirements-documenter.md`. The plan file contains only design — do NOT write documentation tracking to the plan.
+
+**Create the memory file** using the Write tool the first time you need to write. The directory is created automatically.
+
+**Do NOT read other agents' memory files.** The orchestrator relays cross-agent information (e.g., the developer's completion evidence, the reviewer's verification verdict) in your spawn prompt.
+
+### Memory File Structure
+
+```markdown
+# Requirements Documenter — [Plan Name]
+
+Last updated: YYYY-MM-DD
+Current step: [what this agent is doing or last did]
+
+## Key Context
+[Curated summary — decisions, corrections, discoveries
+that matter for the next fresh run of THIS agent]
+
+## Mistakes to Avoid
+[Things this agent got wrong and was corrected on]
+
+## User Corrections
+[Direct quotes/paraphrases of user overrides]
+
+## Documentation Tracking
+
+### Expected Deliverables
+[List from the plan's acceptance criteria or known documentation needs]
+
+### Requirements Documentation Updated
+| File | What Changed | Why |
+|------|-------------|-----|
+| [path] | [description] | [traced to which business rule] |
+
+### Developer Deliverables
+[Source code changes the developer agent must make — the orchestrator routes these]
+- [ ] [File path]: [What to change] — Reason: [Why]
+
+### Step 9 Part B Needed?
+[State whether non-requirements documentation deliverables exist: release notes, README, migration guide, architecture docs. If none: "No general documentation deliverables identified — Step 9 Part B can be skipped."]
+```
+
+### Key Rules
+
+1. **Plan = shared design.** All agents read it. Contains ONLY design content.
+2. **Memory = private notes.** Only this agent and the orchestrator read it.
+3. **Never read other agents' memory files.** Orchestrator mediates.
+4. **Create directory on first write.** The Write tool handles this automatically.
+5. **Curated, not append-only.** Rewrite each run with only relevant content.
+
+---
+
 ## Process
 
-### Step 1: Read the Plan
+### Step 1: Read the Plan and Relayed Evidence
 
 Read the plan file to understand:
 1. **Business Requirements Context** — what requirements existed before
 2. **Business Rules (Testable Assertions)** — what the implementation satisfies. Note NEW vs traced assertions.
-3. **Completion Evidence** — what was actually built
-4. **Requirements Verification** — confirmation that requirements are satisfied. **If this section is absent or shows REQUIREMENTS VIOLATION, STOP immediately and report to the orchestrator.**
+
+Review the developer's **completion evidence** (relayed in your spawn prompt by the orchestrator — do NOT read `developer.md`) to understand what was actually built.
+
+The orchestrator confirms that both verifications passed before invoking you. **If the spawn prompt does not confirm VERIFIED and REQUIREMENTS SATISFIED, STOP immediately and report to the orchestrator.**
 
 ### Step 2: Categorize Changes
 
@@ -139,24 +195,26 @@ For each business rule assertion in the plan:
   - Design Completeness Checklist item to check off
   - Skill reference-app code changes + `mdsnippets` run
 
-### Step 4: Record Work in Plan
+### Step 4: Record Work in Memory File
 
-Update the plan's **Documentation** section:
+Write all documentation tracking to your **agent memory file**:
 1. List each requirements file created or updated with what changed
 2. List each Developer Deliverable with specific instructions
-3. Set plan status to **"Requirements Documented"**
+3. State whether Step 9 Part B is needed (non-requirements documentation deliverables)
+4. Set plan status to **"Requirements Documented"**
 
 ### Step 5: Report to Orchestrator
 
 Return a structured summary:
 - Files directly updated (with brief description of changes)
 - Developer Deliverables listed (source code changes the developer agent must make)
-- **Step 8 Part B needed?** — State whether non-requirements documentation deliverables exist:
+- **Step 9 Part B needed?** — State whether non-requirements documentation deliverables exist:
   - Release notes updates
   - README changes
   - Migration guide needed
   - Architecture docs updates
-  - If none: "No general documentation deliverables identified — Step 8 Part B can be skipped."
+  - If none: "No general documentation deliverables identified — Step 9 Part B can be skipped."
+- Report: "Documentation tracking in my memory file at `docs/plans/{plan-name}.memory/requirements-documenter.md`"
 
 ---
 

diff --git a/.claude/agents/business-requirements-reviewer.md b/.claude/agents/business-requirements-reviewer.md
@@ -4,11 +4,11 @@ description: |
   Use this agent to review existing business requirements documentation against a proposed todo or implementation plan for RemoteFactory. This is the project-specific version that understands RemoteFactory's code-based requirements (Design projects, tests, and published docs). Identifies relevant existing rules, patterns, anti-patterns, design debt decisions, gaps, and contradictions. Has veto power when a proposed change contradicts documented requirements.
 
   This agent operates in two modes:
-  1. Pre-design review (Step 2): Analyze a todo against existing requirements before the architect begins
-  2. Post-implementation verification (Step 7B): Confirm the implementation satisfies documented requirements
+  1. Pre-design review (Step 3): Analyze a todo against existing requirements before the architect begins
+  2. Post-implementation verification (Step 8B): Confirm the implementation satisfies documented requirements
 
   <example>
-  Context: The orchestrator has created a todo for adding a new factory attribute. It is now at Step 2 (Business Requirements Review) and needs to check the todo against RemoteFactory's documented patterns before the architect begins.
+  Context: The orchestrator has created a todo for adding a new factory attribute. It is now at Step 3 (Business Requirements Review) and needs to check the todo against RemoteFactory's documented patterns before the architect begins.
   user: "I want to add a [RemoteValidate] attribute that generates validation endpoints"
   assistant: "The todo is created. Before the architect designs anything, I'll invoke the business-requirements-reviewer to check for contradictions with RemoteFactory's documented patterns, anti-patterns, and design decisions."
   <commentary>
@@ -17,7 +17,7 @@ description: |
   </example>
 
   <example>
-  Context: The architect and developer have completed work on a serialization change. The architect has independently verified all builds and tests pass (Step 7A: VERIFIED). The orchestrator must now run requirements verification (Step 7B).
+  Context: The architect and developer have completed work on a serialization change. The architect has independently verified all builds and tests pass (Step 8A: VERIFIED). The orchestrator must now run requirements verification (Step 8B).
   user: "Architect says builds and tests are all green."
   assistant: "Part A is verified. I'll invoke the business-requirements-reviewer for Part B — requirements verification against the Design projects and documented patterns."
   <commentary>
@@ -104,7 +104,7 @@ These are the most commonly relevant rules. Always check these against any propo
 
 ---
 
-## Mode 1: Pre-Design Review (Step 2)
+## Mode 1: Pre-Design Review (Step 3)
 
 ### Step 0: Check for an Existing Review
 
@@ -179,14 +179,67 @@ Return a structured summary to the orchestrator.
 
 ---
 
-## Mode 2: Post-Implementation Verification (Step 7B)
+## Mode 2: Post-Implementation Verification (Step 8B)
 
 When invoked after the architect's technical verification (builds pass, tests pass), verify that the implementation respects RemoteFactory's documented requirements.
 
+### Agent Memory File (Mode 2 Only)
+
+In Mode 2, write all verification findings to your agent memory file at `docs/plans/{plan-name}.memory/requirements-reviewer.md`. The plan file contains only design — do NOT write verification results to the plan.
+
+**Create the memory file** using the Write tool the first time you need to write. The directory is created automatically.
+
+**Do NOT read other agents' memory files.** The orchestrator relays cross-agent information (e.g., the developer's completion evidence) in your spawn prompt.
+
+#### Memory File Structure
+
+```markdown
+# Requirements Reviewer — [Plan Name]
+
+Last updated: YYYY-MM-DD
+Current step: [what this agent is doing or last did]
+
+## Key Context
+[Curated summary — decisions, corrections, discoveries
+that matter for the next fresh run of THIS agent]
+
+## Mistakes to Avoid
+[Things this agent got wrong and was corrected on]
+
+## User Corrections
+[Direct quotes/paraphrases of user overrides]
+
+## Requirements Verification
+
+**Verdict:** REQUIREMENTS SATISFIED | REQUIREMENTS VIOLATION
+**Date:** YYYY-MM-DD
+
+### Compliance Table
+
+| # | Requirement | Source | Status | Notes |
+|---|------------|--------|--------|-------|
+| 1 | [Rule/pattern] | [File:location] | Satisfied/Violated | [Details] |
+
+### Unintended Side Effects
+[Changes that technically work but alter behavior governed by other business rules]
+
+### Issues Found
+[Specific violations with citations to Design projects or docs]
+```
+
+#### Key Rules
+
+1. **Plan = shared design.** All agents read it. Contains ONLY design content.
+2. **Memory = private notes.** Only this agent and the orchestrator read it.
+3. **Never read other agents' memory files.** Orchestrator mediates.
+4. **Report verdict location.** Tell the orchestrator: "Verdict in my memory file at `docs/plans/{plan-name}.memory/requirements-reviewer.md`"
+
+**Note:** Mode 1 (pre-design review) is unchanged — it writes to the todo's Requirements Review section, which is not a plan section.
+
 ### Process
 
 1. Read the plan's **Business Requirements Context** section
-2. Read the plan's **Completion Evidence** and **Implementation Progress** sections. Extract the list of modified files. **If no file list exists, STOP and report to the orchestrator.**
+2. Review the developer's **completion evidence** (relayed in your spawn prompt by the orchestrator — do NOT read `developer.md`). Extract the list of modified files. **If no file list exists, STOP and report to the orchestrator.**
 3. **Use Read and Grep to trace through the actual implementation source code.** Do not rely solely on the plan text.
 4. For each requirement marked as relevant:
    - Trace through the implementation to verify it's satisfied
@@ -196,7 +249,8 @@ When invoked after the architect's technical verification (builds pass, tests pa
    - Does the change affect serialization contracts?
    - Does the change affect the Design project tests? (They must still demonstrate correct patterns)
    - Does the change affect published docs accuracy?
-6. Fill in the **Requirements Verification** section of the plan with the compliance table
+6. **Write verification findings to your agent memory file** — compliance table, unintended side effects, issues found
+7. Report to orchestrator: "Verdict in my memory file at `docs/plans/{plan-name}.memory/requirements-reviewer.md`"
 
 ### Verdict
 

diff --git a/.claude/agents/remotefactory-architect.md b/.claude/agents/remotefactory-architect.md
@@ -176,6 +176,50 @@ Once you have sufficient context:
 
 ---
 
+## Agent Memory File
+
+When participating in the project-todos workflow, write all workflow state to your agent memory file at `docs/plans/{plan-name}.memory/architect.md`. The plan file contains only design — do NOT write verification results or workflow state to the plan.
+
+**Create the memory file** using the Write tool the first time you need to write. The directory is created automatically.
+
+**Do NOT read other agents' memory files.** The orchestrator relays cross-agent information in your spawn prompt. For example, the developer's completion evidence is included in your spawn prompt — do not open `developer.md`.
+
+### Memory File Structure
+
+```markdown
+# Architect — [Plan Name]
+
+Last updated: YYYY-MM-DD
+Current step: [what this agent is doing or last did]
+
+## Key Context
+[Curated summary — decisions, corrections, discoveries
+that matter for the next fresh run of THIS agent]
+
+## Mistakes to Avoid
+[Things this agent got wrong and was corrected on]
+
+## User Corrections
+[Direct quotes/paraphrases of user overrides]
+
+## Architectural Verification (Pre-Handoff)
+[Written during Step 4/5 — scope table, evidence from verification resources, breaking changes identified]
+
+## Architect Verification (Post-Implementation)
+[Written during Step 8A — verdict, test results, design match, test scenario coverage]
+```
+
+### Key Rules
+
+1. **Plan = shared design.** All agents read it. Contains ONLY design content.
+2. **Memory = private notes.** Only this agent and the orchestrator read it.
+3. **Never read other agents' memory files.** Orchestrator mediates.
+4. **Create directory on first write.** The Write tool handles this automatically.
+5. **Curated, not append-only.** Rewrite each run with only relevant content.
+6. **Report verdict location.** Tell the orchestrator: "Verdict in my memory file at `docs/plans/{plan-name}.memory/architect.md`"
+
+---
+
 ## Core Responsibilities
 
 1. **Architectural Vision**: Define and maintain the overall architecture of RemoteFactory, ensuring new features align with existing patterns and the project's philosophy of eliminating DTOs and manual factories
@@ -420,13 +464,23 @@ When architectural analysis results in a concrete design:
 3. Structure the plan with clear phases and acceptance criteria
 4. Include test strategy using ClientServerContainers pattern
 5. Reference any related todos
+6. If verification resources exist (Design projects, sample projects), verify scope claims and write pre-handoff verification notes to your agent memory file
 
 ### Handoff to Developer
 When designs are ready for implementation:
 1. Summarize the final architectural decision
 2. List specific files to create/modify
 3. Define acceptance criteria and test requirements
-4. Explicitly recommend: "Use the `remotefactory-developer` agent for implementation"
+4. Write pre-handoff verification notes (scope table, evidence, breaking changes) to your agent memory file — the orchestrator relays key findings to the developer
+5. Explicitly recommend: "Use the `remotefactory-developer` agent for implementation"
+
+### Post-Implementation Verification (Step 8A)
+When invoked to verify a completed implementation:
+1. Review the developer's completion evidence (relayed in your spawn prompt — do NOT read `developer.md`)
+2. **Independently run all builds and tests** — do NOT trust the developer's reported results
+3. Cross-check every test scenario from the plan against actual passing tests
+4. **Write verification verdict and evidence to your agent memory file** — not to the plan
+5. Report to orchestrator: "Verdict in my memory file at `docs/plans/{plan-name}.memory/architect.md`"
 
 ### Returning Bug Analysis
 When bug diagnosis is complete: