aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/tasks/atomic-refactor-execute.md

@@ -0,0 +1,391 @@
+# Atomic Design Refactoring Execute
+
+> Task ID: atomic-refactor-execute
+> Agent: Brad Frost (Design System)
+> Version: 2.0.0
+>
+> **ATUALIZADO Jan/2026:** Adicionados gates anti-over-engineering.
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[atomic-refactor-plan]` · enables: `[validate-design-fidelity]` · workflow: `refactoring`
+
+## Input Schema
+- **requires:** Output from `atomic-refactor-plan`
+- **format:** YAML data
+- **location:** `outputs/design-system/{project}/refactoring/refactor-plan.yaml`
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/refactoring/refactor-results.md`
+- **format:** Markdown report
+- **consumed_by:** validate-design-fidelity
+
+## ⛔ GATES OBRIGATÓRIOS (LER PRIMEIRO)
+
+### GATE 0: Devo Atomizar?
+```bash
+wc -l {arquivo}
+# Se <500 → NÃO atomize, apenas organize inline
+```
+
+### GATE 1: Antes de Cada Hook
+```
+PERGUNTA: Esse hook será usado em OUTRO componente?
+SE NÃO → não crie o hook, mantenha useState inline
+```
+
+### GATE 2: Validação Final
+```bash
+find {pasta-criada} -name "*.ts" -o -name "*.tsx" | xargs wc -l | tail -1
+# Se linhas_depois > linhas_antes → FALHA, simplificar
+```
+
+## Description
+
+Executes Atomic Design refactoring on a single component, decomposing a monolithic template into types, hooks, atoms, molecules, organisms, and an orchestrating template.
+
+**IMPORTANTE:** Apenas criar hooks que serão REUSADOS. useState específicos devem ficar inline.
+
+## Prerequisites
+
+- Target component identified (e.g., `CoursesTemplate.tsx`)
+- Reference pattern exists (e.g., `app/components/ops/users/`)
+- Shared components available in `app/components/shared/` (if needed)
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Select Target Component**
+   - Component file path
+   - Confirm line count and complexity
+
+2. **Review Current Structure**
+   - List `useState` hooks (→ custom hooks)
+   - List `render{X}()` functions (→ organisms)
+   - Identify UI patterns (→ molecules)
+   - Identify small UI elements (→ atoms)
+
+3. **Confirm Output Structure**
+   - Target folder path
+   - File naming conventions
+   - Dependencies on shared components
+
+### Steps
+
+1. **Analyze Component**
+   - Read entire file
+   - Extract all `useState` declarations
+   - Extract all `render{X}()` functions
+   - Identify JSX patterns repeated 2+ times
+   - Check: useState count >= 0 AND render function count >= 0 AND repeated patterns >= 0 — log "Analysis: {hooks} useState, {renders} render functions, {patterns} repeated patterns"
+
+2. **Create Folder Structure**
+   ```
+   {domain}/{component-name}/
+   ├── types.ts
+   ├── index.ts
+   ├── {ComponentName}Template.tsx
+   ├── hooks/
+   │   └── index.ts
+   ├── atoms/
+   │   └── index.ts (if needed)
+   ├── molecules/
+   │   └── index.ts
+   └── organisms/
+       └── index.ts
+   ```
+   - Check: `test -d {component-name}/hooks/` AND `test -d {component-name}/organisms/` — abort with "Directory structure creation failed: {missing dir}"
+
+3. **Extract Types**
+   - Create `types.ts` with all interfaces
+   - Include prop types for all sub-components
+   - Add type exports
+   - Check: `npx tsc --noEmit` exits with 0 for types.ts — abort with "TypeScript compilation failed: {error}"
+
+4. **Extract Hooks** ⚠️ GATE 1
+   - **ANTES de criar cada hook:** Esse hook será usado em OUTRO componente?
+   - Se NÃO → **NÃO CRIE**, mantenha useState inline com comentários
+   - Group related `useState` into custom hooks **APENAS SE REUSÁVEIS**
+   - Pattern: `use{Domain}{Feature}` (e.g., `useCoursesFilters`)
+   - Each hook handles one concern
+   - Export from `hooks/index.ts`
+   - Check: `npx tsc --noEmit` passes for hooks/ AND no circular imports detected AND orphan hook count == 0 — abort with "Hook issues: {error or orphan list}"
+
+5. **Extract Atoms** (if needed)
+   - Small, stateless UI elements
+   - Examples: Avatar, Badge, Icon wrapper
+   - Only if not already in `shared/atoms/`
+   - Check: `npx tsc --noEmit` passes for atoms/ AND no missing imports — log "{N} atoms extracted successfully"
+
+6. **Extract Molecules**
+   - Combinations of atoms/primitives
+   - Examples: SearchInput, StatCard, AlertMessage
+   - Check shared/ first before creating
+   - Check: `npx tsc --noEmit` passes for molecules/ AND all atom imports resolve — log "{N} molecules extracted successfully"
+
+7. **Extract Organisms**
+   - One organism per `render{X}()` function
+   - Named `{X}View.tsx` or `{X}Section.tsx`
+   - Receives props, renders molecules
+   - Export from `organisms/index.ts`
+   - Check: `npx tsc --noEmit` passes for organisms/ AND all molecule/atom imports resolve — log "{N} organisms extracted successfully"
+
+8. **Create Template Orchestrator**
+   - Main component, ~100-200 lines max
+   - Imports and uses all hooks
+   - Renders organisms in layout
+   - Handles top-level state coordination
+   - Check: template file < 200 lines AND `npx tsc --noEmit` passes — abort with "Template orchestrator too large ({lines} lines) or has type errors"
+
+9. **Update Imports**
+   - Update any files importing the old component
+   - Change from direct import to folder import
+   - Check: `npx tsc --noEmit` passes project-wide AND grep for old import path returns 0 matches — abort with "Broken imports found: {list}"
+
+10. **Verify TypeScript**
+    - Run `npx tsc --noEmit`
+    - Fix any type errors
+    - Check: `npx tsc --noEmit` exits with 0 — abort with "TypeScript errors remain: {count} errors"
+
+11. **Update Documentation**
+    - Mark component as done in ROADMAP.md
+    - Update file count in status
+    - Check: ROADMAP.md contains component marked as done AND file count updated — abort with "Documentation not updated: {missing update}"
+
+## Output
+
+For a component like `CoursesTemplate.tsx` (1,987 lines):
+
+```
+app/components/creator/courses/
+├── types.ts                    # ~80 lines
+├── index.ts                    # ~5 lines
+├── CoursesTemplate.tsx         # ~150 lines ✨
+├── hooks/
+│   ├── index.ts
+│   ├── useCoursesData.ts       # ~60 lines
+│   ├── useCoursesFilters.ts    # ~40 lines
+│   ├── useNewCourseForm.ts     # ~80 lines
+│   └── useCoursePipeline.ts    # ~50 lines
+├── molecules/
+│   ├── index.ts
+│   ├── CourseCard.tsx          # ~80 lines
+│   ├── PipelineStepBadge.tsx   # ~40 lines
+│   └── CourseStatusBadge.tsx   # ~35 lines
+└── organisms/
+    ├── index.ts
+    ├── CoursesHeader.tsx       # ~60 lines
+    ├── CoursesListView.tsx     # ~120 lines
+    ├── CourseDetailView.tsx    # ~150 lines
+    ├── NewCourseView.tsx       # ~180 lines
+    ├── BriefEditorView.tsx     # ~200 lines
+    └── PipelineView.tsx        # ~140 lines
+```
+
+**Result**: 1,987 lines → 17 files, each <200 lines
+
+## Failure Handling
+
+- **Tests fail after refactor:** Revert to pre-refactor state. Compare diff to identify breaking change. Fix and re-run
+- **Visual regression detected:** Run *visual-test to capture exact differences. Fix token references or CSS specificity issues
+- **Build errors:** Check import paths updated. Verify component name changes propagated to all consumers
+- **Refactor plan outdated:** If codebase changed since plan, re-run *refactor-plan before executing
+
+## Success Criteria
+
+### ⛔ GATE 2 (Obrigatório)
+- [ ] **Linhas totais ≤ original** (se aumentou → simplificar)
+- [ ] **≤7 arquivos criados** (se mais → consolidar)
+- [ ] **0 hooks órfãos** (se tem → mover inline)
+
+### Demais Critérios
+- [ ] useState reusáveis extraídos para hooks (específicos ficam inline)
+- [ ] All `render{X}()` extracted to organisms
+- [ ] Repeated UI patterns extracted to molecules
+- [ ] Template orchestrator <200 lines
+- [ ] Each file <200 lines
+- [ ] `npx tsc --noEmit` passes
+- [ ] Component renders correctly in browser
+- [ ] ROADMAP.md updated
+
+## Error Handling
+
+- **Circular dependency**: Restructure imports, use type-only imports
+- **Missing shared component**: Add to SHARED_REQUESTS.md, wait for Agent 3
+- **Type errors**: Fix before proceeding, don't leave broken code
+- **Component breaks UI**: Revert and analyze, don't commit broken code
+
+## Reference Pattern
+
+Always refer to `app/components/ops/users/` as the canonical example:
+
+```
+ops/users/
+├── types.ts              # Types, configs, constants
+├── index.ts              # Barrel export
+├── OpsUsersTemplate.tsx  # Orchestrator (~195 lines)
+├── hooks/
+│   ├── index.ts
+│   ├── useUsersData.ts
+│   ├── useLinkMindDialog.ts
+│   ├── useCreateUserDialog.ts
+│   └── useRoleDialog.ts
+├── molecules/
+│   ├── index.ts
+│   ├── SearchInput.tsx
+│   ├── StatCard.tsx
+│   ├── AlertMessage.tsx
+│   ├── RoleBadge.tsx
+│   └── AreasTags.tsx
+└── organisms/
+    ├── index.ts
+    ├── UsersPageHeader.tsx
+    ├── UsersStatsGrid.tsx
+    ├── UsersTable.tsx
+    ├── UserTableRow.tsx
+    ├── LinkMindDialog.tsx
+    ├── CreateUserDialog.tsx
+    ├── RoleDialog.tsx
+    └── PendingInvitesSection.tsx
+```
+
+## Extraction Rules
+
+### useState → Custom Hook
+
+```typescript
+// BEFORE (in template)
+const [search, setSearch] = useState('');
+const [filters, setFilters] = useState<Filters>({});
+const filteredData = useMemo(() => ..., [data, search, filters]);
+
+// AFTER (in hooks/useFilters.ts)
+export function useFilters(data: Item[]) {
+  const [search, setSearch] = useState('');
+  const [filters, setFilters] = useState<Filters>({});
+
+  const filteredData = useMemo(() => ..., [data, search, filters]);
+
+  return { search, setSearch, filters, setFilters, filteredData };
+}
+```
+
+### render{X}() → Organism
+
+```typescript
+// BEFORE (in template)
+const renderHeader = () => (
+  <div className="flex justify-between">
+    <h1>Title</h1>
+    <Button onClick={onCreate}>New</Button>
+  </div>
+);
+
+// AFTER (in organisms/Header.tsx)
+interface HeaderProps {
+  title: string;
+  onCreate: () => void;
+}
+
+export const Header: React.FC<HeaderProps> = ({ title, onCreate }) => (
+  <div className="flex justify-between">
+    <h1>{title}</h1>
+    <Button onClick={onCreate}>New</Button>
+  </div>
+);
+```
+
+### Repeated JSX → Molecule
+
+```typescript
+// BEFORE (repeated 3+ times in template)
+<div className="flex items-center gap-2 rounded-lg border p-4">
+  <Icon name={icon} />
+  <span>{label}</span>
+  <span className="text-muted-foreground">{value}</span>
+</div>
+
+// AFTER (in molecules/StatCard.tsx)
+interface StatCardProps {
+  icon: string;
+  label: string;
+  value: string | number;
+}
+
+export const StatCard: React.FC<StatCardProps> = ({ icon, label, value }) => (
+  <div className="flex items-center gap-2 rounded-lg border p-4">
+    <Icon name={icon} />
+    <span>{label}</span>
+    <span className="text-muted-foreground">{value}</span>
+  </div>
+);
+```
+
+## Examples
+
+### Example 1: Refactor Single Component
+
+```bash
+/atomic-refactor-execute app/components/creator/templates/CoursesTemplate.tsx
+```
+
+Output:
+```
+🔍 Uma: Analyzing CoursesTemplate.tsx...
+
+📊 Analysis Results:
+  Total lines: 1,987
+  useState hooks: 14 (→ 4 custom hooks)
+  render functions: 8 (→ 8 organisms)
+  UI patterns: 3 (→ 3 molecules)
+
+📁 Creating structure: app/components/creator/courses/
+
+✓ Created types.ts (82 lines)
+✓ Created hooks/useCoursesData.ts (64 lines)
+✓ Created hooks/useCoursesFilters.ts (38 lines)
+✓ Created hooks/useNewCourseForm.ts (76 lines)
+✓ Created hooks/useCoursePipeline.ts (52 lines)
+✓ Created molecules/CourseCard.tsx (78 lines)
+✓ Created molecules/PipelineStepBadge.tsx (42 lines)
+✓ Created molecules/CourseStatusBadge.tsx (36 lines)
+✓ Created organisms/CoursesHeader.tsx (58 lines)
+✓ Created organisms/CoursesListView.tsx (118 lines)
+✓ Created organisms/CourseDetailView.tsx (146 lines)
+✓ Created organisms/NewCourseView.tsx (178 lines)
+✓ Created organisms/BriefEditorView.tsx (196 lines)
+✓ Created organisms/PipelineView.tsx (138 lines)
+✓ Created CoursesTemplate.tsx (148 lines)
+✓ Created index.ts (5 lines)
+
+🧪 TypeScript check...
+  ✓ npx tsc --noEmit: 0 errors
+
+📝 Updated docs/refactoring/COMPONENT_REFACTORING_ROADMAP.md
+
+📊 Summary:
+  Before: 1 file, 1,987 lines
+  After: 17 files, max 196 lines each
+  Reduction: 90% in main file
+
+✅ Refactoring complete!
+
+Uma says: "Clean architecture is not optional."
+```
+
+## Notes
+
+- Always read the full component before starting
+- Check shared/ for existing molecules before creating new ones
+- Keep orchestrator focused on composition, not business logic
+- Each file should have a single responsibility
+- Commit after each successful component refactoring
+- Test in browser before marking as done
+
+
+## Related Checklists
+
+- `squads/design/checklists/atomic-refactor-checklist.md`
+- `squads/design/checklists/ds-component-quality-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/tasks/atomic-refactor-plan.md

@@ -0,0 +1,262 @@
+# Atomic Design Refactoring Plan
+
+> Task ID: atomic-refactor-plan
+> Agent: Brad Frost (Design System)
+> Version: 2.0.0
+>
+> **ATUALIZADO Jan/2026:** Adicionados gates anti-over-engineering.
+> **Execution Type:** `Hybrid`
+> **Human Checkpoint:** Review and approve the refactoring plan, component classification, and complexity gates before execution begins
+> **Dependencies:** depends_on: `[]` · enables: `[atomic-refactor-execute]` · workflow: `refactoring`
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/refactoring/refactor-plan.yaml`
+- **format:** YAML data
+- **consumed_by:** atomic-refactor-execute
+
+## ⛔ LIÇÃO APRENDIDA (LER PRIMEIRO)
+
+Em Jan/2026 atomizamos 22 componentes. Resultado em alguns casos:
+- FragmentsTab: 475 → 1003 linhas (+111%)
+- 73% dos hooks criados sem reuso externo
+- 476 arquivos <30 linhas (boilerplate)
+
+**Nova regra:** Só incluir na lista componentes que realmente precisam E terão hooks reusáveis.
+
+## Description
+
+Analyzes codebase to identify components that **REALMENTE** need Atomic Design refactoring, classifies them by domain and tier, and generates parallel work distribution plans with ready-to-use agent prompts.
+
+This task automates the analysis workflow used to create `docs/refactoring/COMPONENT_REFACTORING_ROADMAP.md` and `docs/refactoring/PARALLEL_REFACTORING_PLAN.md`.
+
+## Prerequisites
+
+- Codebase with React/TypeScript components
+- At least one reference component already refactored (e.g., `app/components/ops/users/`)
+- `docs/refactoring/` directory exists
+
+## Workflow
+
+### Interactive Elicitation
+
+1. **Select Analysis Scope**
+   - Entire codebase or specific directory
+   - Minimum line threshold (default: 300)
+   - Exclude patterns (e.g., `**/ui/**`, `**/*.test.tsx`)
+
+2. **Configure Work Distribution**
+   - Number of parallel agents (2-5, default: 3)
+   - Distribution strategy: by domain (default) or by tier
+   - Shared components owner (which agent creates shared/)
+
+3. **Review Plan**
+   - Show domain distribution
+   - Confirm tier classification
+   - Preview agent prompts
+
+### Steps
+
+1. **Scan Components**
+   - Find all `.tsx` files in target directory
+   - Count lines per file (excluding imports/whitespace)
+   - Filter by threshold
+   - Check: candidate count > 0 AND each has file path + line count — log "Found {N} components above {threshold} line threshold"
+
+2. **Group by Domain**
+   - Extract domain from path (e.g., `creator/`, `ops/`, `books/`)
+   - Aggregate by domain
+   - Calculate total lines per domain
+   - Check: all candidates assigned to a domain AND no component unassigned — log "{N} domains with {total} components, {lines} total lines"
+
+3. **Classify by Tier**
+   - TIER 1: >800 lines (critical, start first)
+   - TIER 2: 500-800 lines (medium priority)
+   - ~~TIER 3: 300-500 lines~~ **REMOVIDO v2.0** - muito pequeno, organizar inline
+   - Check: every candidate has TIER 1 or TIER 2 classification — log "TIER 1: {N1} components, TIER 2: {N2} components"
+
+4. **⛔ NEW: Filtrar por Potencial de Reuso**
+   - Para cada componente, perguntar: "Os hooks serão reusados?"
+   - Se NÃO → **EXCLUIR DA LISTA**
+   - Apenas componentes com hooks reusáveis em 2+ lugares passam
+   - Check: all remaining candidates have reusable hooks (used in 2+ places) — log "{N} components passed reuse filter, {excluded} excluded"
+
+5. **Identify Patterns**
+   - Scan for `render{X}()` functions → organisms
+   - Count `useState` hooks → custom hooks needed
+   - Find repeated UI patterns → molecules
+   - Check: each component has render function count + useState count + repeated pattern count — log "Pattern analysis: {hooks} hooks, {renders} render fns, {patterns} repeated patterns"
+
+5. **Distribute Work**
+   - Group domains into N agents
+   - Balance line count across agents (±20%)
+   - Ensure no domain split across agents
+   - Check: max agent line count <= min agent line count * 1.4 (within 20% balance) — log "Distribution: {N} agents, range {min}-{max} lines, variance {pct}%"
+
+6. **Generate Shared Components List**
+   - Identify commonly needed molecules
+   - List hooks that can be generalized
+   - Create shared component checklist
+   - Check: shared component list count >= 0 AND generalized hooks list exists — log "{N} shared molecules, {M} generalizable hooks identified"
+
+7. **Generate Agent Prompts**
+   - Create detailed prompt for each agent
+   - Include domain assignments
+   - Add checklist and rules
+   - Include reference to existing pattern
+   - Check: prompt file count == agent count AND each file size > 0 — abort with "Prompt generation failed for agent {N}"
+
+8. **Generate Documentation**
+   - Update/create COMPONENT_REFACTORING_ROADMAP.md
+   - Update/create PARALLEL_REFACTORING_PLAN.md
+   - Create SHARED_REQUESTS.md template
+   - Check: `test -f COMPONENT_REFACTORING_ROADMAP.md` AND `test -f PARALLEL_REFACTORING_PLAN.md` AND `test -f SHARED_REQUESTS.md` — abort with "Documentation generation failed: {missing file}"
+
+## Output
+
+- **docs/refactoring/COMPONENT_REFACTORING_ROADMAP.md**: Complete inventory
+- **docs/refactoring/PARALLEL_REFACTORING_PLAN.md**: Work distribution
+- **docs/refactoring/SHARED_REQUESTS.md**: Shared component request template
+- **Console output**: Ready-to-use prompts for each agent
+
+## Related Checklists
+
+- `squads/design/checklists/atomic-refactor-checklist.md`
+- `squads/design/checklists/ds-component-quality-checklist.md`
+
+### Output Format
+
+```markdown
+# Refactoring Analysis Complete
+
+## Summary
+- Components found: {count}
+- Total lines: {lines}
+- Domains: {domains}
+- Agents: {n}
+
+## Distribution
+
+| Agent | Domains | Components | Lines |
+|-------|---------|------------|-------|
+| 1 | creator/, lms/ | 21 | ~12,600 |
+| 2 | ops/, books/, auth/ | 39 | ~20,400 |
+| 3 | shared/, design-system/, minds/ | 69 | ~35,300 |
+
+## Prompts Ready
+
+Copy the prompt for each agent from:
+- docs/refactoring/prompts/agent-1-prompt.md
+- docs/refactoring/prompts/agent-2-prompt.md
+- docs/refactoring/prompts/agent-3-prompt.md
+```
+
+## Failure Handling
+
+- **Component too complex to refactor atomically:** Decompose into sub-components first. Create intermediate refactoring step
+- **Missing design tokens for component:** Run *tokenize for the component's patterns before planning refactor
+- **Breaking changes unavoidable:** Document all consumers. Create compatibility layer with deprecation timeline (minimum 2 sprints)
+- **No test coverage on target component:** Write characterization tests BEFORE refactoring to prevent regressions
+
+## Success Criteria
+
+- [ ] All components >threshold identified
+- [ ] Components classified by tier (TIER 1/2/3)
+- [ ] Domains grouped without overlap
+- [ ] Work balanced across agents (±20% lines)
+- [ ] Agent prompts include all rules and checklists
+- [ ] Documentation files generated/updated
+
+## Error Handling
+
+- **No reference component**: Suggest running `atomic-refactor-execute` on smallest component first
+- **Single domain only**: Suggest using single agent or splitting by subdomain
+- **Imbalanced distribution**: Warn and suggest manual adjustment
+- **Existing files**: Ask to overwrite or append
+
+## Examples
+
+### Example 1: Full Analysis
+
+```bash
+/atomic-refactor-plan
+```
+
+Output:
+```
+🔍 Uma: Analyzing codebase for refactoring opportunities...
+
+📊 Scan Results:
+  Directory: app/components/
+  Threshold: 300 lines
+  Files scanned: 847
+  Candidates found: 131
+
+📁 Domains Found:
+  ops/           20 components  ~11,200 lines
+  design-system/ 19 components  ~11,700 lines
+  books/         18 components  ~8,600 lines
+  ...
+
+📈 Tier Classification:
+  TIER 1 (>800)  : 10 components  ~10,800 lines ⚠️ Priority
+  TIER 2 (500-800): 41 components  ~25,500 lines
+  TIER 3 (300-500): 80 components  ~29,000 lines
+
+🤖 Work Distribution (3 agents):
+  Agent 1: creator/, lms/       → 21 components (~12,600 lines)
+  Agent 2: ops/, books/, auth/  → 39 components (~20,400 lines)
+  Agent 3: shared/, design-system/, minds/, prd/, marketing/, sales/
+                                → 69 components (~35,300 lines)
+
+📝 Generated:
+  ✓ docs/refactoring/COMPONENT_REFACTORING_ROADMAP.md
+  ✓ docs/refactoring/PARALLEL_REFACTORING_PLAN.md
+  ✓ docs/refactoring/prompts/agent-1-prompt.md
+  ✓ docs/refactoring/prompts/agent-2-prompt.md
+  ✓ docs/refactoring/prompts/agent-3-prompt.md
+
+🚀 Ready! Copy prompts and start agents in parallel.
+
+Uma says: "Structure before style. Architecture before aesthetics."
+```
+
+### Example 2: Specific Directory
+
+```bash
+/atomic-refactor-plan app/components/creator/ --agents=2 --threshold=400
+```
+
+Analyzes only `creator/` with custom settings.
+
+## Tier Classification Reference
+
+| Tier | Lines | Priority | Typical Effort |
+|------|-------|----------|----------------|
+| 1 | >800 | Critical | 2-4 hours |
+| 2 | 500-800 | Medium | 1-2 hours |
+| 3 | 300-500 | Lower | 30-60 min |
+
+## Agent Prompt Template
+
+Each generated prompt includes:
+
+1. **Domain Assignment**: Which directories this agent owns
+2. **Reference Component**: Where to look for the pattern
+3. **TIER 1 Priority**: Which component to start with
+4. **TIER 2 List**: Remaining components in priority order
+5. **Target Structure**: Folder/file structure for decomposition
+6. **Rules**: What NOT to modify (other domains, shared/)
+7. **Checklist**: Per-component steps to follow
+8. **Communication**: How to request shared components
+
+## Notes
+
+- Run this task before starting any large refactoring effort
+- Agent 3 (shared owner) should complete shared components before others start
+- All agents should `git pull` frequently to avoid conflicts
+- Update status in ROADMAP.md as components are completed
+- Use SHARED_REQUESTS.md to coordinate cross-agent dependencies
+
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.