nurosys-agents 2.0.0 → 2.1.0

package/.agent/frontend/skills/architect/SKILL.md

@@ -1,644 +1,486 @@
 ---
 name: architect
-description: Research the current React/Next.js codebase, decompose a feature or enhancement into logical modules with dependency ordering, and produce a gated architecture plan plus per-module implementation prompts. Use when the user asks to architect, break down, design, or phase a multi-file feature, module, refactor, or enhancement.
+description: Frontend technical planner. Reads `<feature>_UX_PLAN.md` (produced by `/ux-architect`), decomposes the UX into ordered technical modules (page-layer, view-layer, hooks, services), consults read-only sub-agents for cross-cutting concerns (auth, security), and writes ONLY planning documents under `documentation/features/<feature>/`. NEVER WRITES CODE. Hands off to `/module-runner` for execution. Trigger with `/architect documentation/features/<feature_name>/` or `/architect <feature description>`.
+disable-model-invocation: false
 ---
 
-# Skill: architect
+# Skill: architect (frontend)
 
-Use this skill when the work is larger than a small single-file change and you need a reusable implementation blueprint before coding.
+The technical planner. Translates a UX plan into ordered, autonomously-executable technical modules. Produces documents the user reviews before any code is written.
 
-The goal is to:
+## Hard guarantee — architect NEVER writes code
 
-1. Study the existing this architecture first.
-2. Break the requested work into small, independently implementable modules.
-3. Produce one master architecture plan.
-4. Stop for approval.
-5. After approval, generate per-module prompt files that can be handed to an AI implementer and that align with this repo's existing feature workflow.
-6. Maintain persistent implementation memory in `project-memory/core-memory.md` as each module is completed.
+**What architect produces (and ONLY this):**
 
-## When to trigger
+- `documentation/features/<feature_name>/<feature>_MODULE_WISE_PLAN.md` — master technical plan
+- `documentation/features/<feature_name>/<feature>_MODULE_<N>_<MODULE_NAME>.md` — one prompt per module (input for `/module-runner`)
 
-- User asks to "architect", "break down", "plan", "design", or "phase" a feature.
-- The work spans multiple areas such as `src/app`, `src/views`, `src/components`, `src/services`, `src/hooks`, `src/utils`, or `src/app/api`.
-- You need to understand existing repo patterns before proposing changes.
-- The user wants a module-by-module implementation plan for a new feature, enhancement, or significant refactor.
+**What architect MUST NOT touch:**
 
-## Output locations
+- Anything under `src/` (pages, components, hooks, services, styles)
+- Tests
+- Git (no commits, no branches, no pushes)
+- Dependencies (`package.json`)
+- `project-memory/` except optionally noting "feature X planned on <date>" in `core-memory.md` — and even that is deferred to `/module-runner`'s wrap-up
 
-All outputs go under **`Documentation/features/<feature_name>/`**. Create that folder when generating the first artifact for a feature.
+If you feel the urge to write code "just to validate the plan", stop. The plan is a document; execution is `/module-runner`'s job.
 
-| File | Purpose |
-|------|---------|
-| `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md` | Master architecture plan with scope, modules, dependencies, implementation order, and file inventory |
-| `Documentation/features/<feature_name>/MODULE_<N>_<MODULE_NAME>.md` | Per-module implementation prompt file, generated only after plan approval |
+---
 
-Naming rules:
+## When to trigger
+
+- A `/ux-architect` session completed and the UX plan was approved
+- User asks to "architect", "plan modules for", "decompose", or "design the technical plan for" a feature
+- Work spans more than one module or layer
 
-- `<FEATURE_NAME>`: `UPPER_SNAKE_CASE` such as `PDF_EXPORT_QUEUE` or `BRAND_AUDIT_FILTERS`
-- `<feature_name>`: `snake_case` such as `pdf_export_queue` or `brand_audit_filters`
-- `<MODULE_NAME>`: short `UPPER_SNAKE_CASE` label such as `API_ROUTE`, `VIEW_STATE`, `PDF_WIDGET`
+For UI-heavy features, `/ux-architect` runs first. For purely technical refactors with no UX change (renaming a hook, restructuring services), `/architect` can run standalone.
 
-## Expected behavior
+---
 
-This skill is intentionally two-stage:
+## Output locations
 
-1. First run: create only the master architecture plan in `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`
-2. Wait for explicit approval
-3. Second run after approval: generate multiple prompt files, one per module, under `Documentation/features/<feature_name>/`
+| File | Purpose |
+|------|---------|
+| `<feature>_MODULE_WISE_PLAN.md` | Master plan: modules, dependencies, contracts, rollout |
+| `<feature>_MODULE_<N>_<MODULE_NAME>.md` | Per-module prompt consumed by `/module-runner` |
 
-If you only see a single architecture document after the first run, that is correct behavior, not a failure.
+Naming:
+- `<feature_name>` is `snake_case` (e.g. `user_profile_drawer`)
+- `<N>` is module number (e.g. `1`, `2`, `3`)
+- `<MODULE_NAME>` is abbreviated `UPPER_SNAKE_CASE` (e.g. `PAGE_LAYER`, `EDIT_DIALOG`)
 
 ---
 
-## Phase 0 - Prerequisites (HARD STOP)
-
-> Goal: confirm project-memory artifacts exist before doing any work. This skill is grounded in those documents and cannot produce a useful plan without them.
+## Phase 0 — Prerequisites (HARD STOP)
 
-Check that **all** of these files exist:
+Required project-memory files:
 
 - `project-memory/constitution.md`
+- `project-memory/architecture.md`
 - `project-memory/repo-map.md`
 - `project-memory/auth-model.md`
-- `project-memory/quality-playbook.md`
+- `project-memory/design-system.md`
 - `project-memory/core-memory.md`
 
-If **any** are missing, STOP immediately. Do not proceed to Phase 1. Do not write a partial plan. Respond to the user exactly with:
+If any missing, **STOP** and respond:
 
-> ⚠️  `/architect` requires the `project-memory/` artifacts to ground the plan in this project's actual rules, architecture, and history. The following files are missing:
->
+> ⚠️ `/architect` requires `project-memory/` artifacts to ground the plan. Missing:
 > - [list each missing file]
 >
-> Please run `/create-blueprint all` first (or `/create-blueprint <artifact>` for individual ones), then re-invoke `/architect <your feature>`.
-
-Only continue to Phase 1 once every file above is present.
-
----
-
-## Phase 1 - Research and discovery
-
-> Goal: understand the current codebase structure and constraints before designing modules.
+> Run `/create-blueprint all` (or `/create-blueprint <artifact>` for individual ones), then re-invoke `/architect`.
 
-### 1.1 Read foundation docs first
+Required UX plan (for UI features):
 
-Read these in order:
+If the user invocation references a feature folder OR the feature has any UI surface:
 
-1. `project-memory/constitution.md`
-2. `project-memory/repo-map.md`
-3. `project-memory/auth-model.md`
-4. `project-memory/quality-playbook.md`
-5. `project-memory/core-memory.md`
-6. `.agent/workflows/build-feature-react.workflow.md`
-7. `.agent/skills/feature-workflow/SKILL.md`
-8. `.agent/templates/FEATURE_PLAN.md`
-9. `.agent/templates/REVIEW_REPORT.md`
-10. `.agent/templates/TEST_PLAN.md`
+- `documentation/features/<feature_name>/<feature>_UX_PLAN.md` MUST exist.
 
-These files define the repo's non-negotiable process and where code belongs.
+If absent and the feature has UI, **STOP** and respond:
 
-If `project-memory/core-memory.md` does not exist yet, create it before finalizing the first architecture plan that will use this skill.
+> ⚠️ This feature has UI but no UX plan exists. Run `/ux-architect <feature>` first — it'll design the layout, component reuse, forms, and states. Then re-invoke `/architect documentation/features/<feature_name>/`.
 
-### 1.2 Map the existing architecture
+For purely technical refactors with no UX change, the UX plan is optional. Confirm with the user before skipping.
 
-Before proposing modules, inspect the actual code paths involved in the feature and note existing patterns.
-
-Always identify:
-
-- Route entry points in `src/app/**`
-- Feature views in `src/views/**`
-- Shared UI in `src/components/**`
-- Hooks in `src/hooks/**`
-- Service/data logic in `src/services/**`
-- Shared helpers in `src/utils/**`
-- Config and contracts in `src/configs/**` and `src/types/**`
-- Any API/BFF handlers in `src/app/api/**`
-- Auth-sensitive touchpoints in:
-  - `src/contexts/authContext.tsx`
-  - `src/utils/auth.ts`
-  - `src/configs/authConfig.ts`
-  - `src/types/auth.ts`
-
-Trace the real flow for the feature area. Typical shapes in this repo are:
-
-```text
-page.tsx -> view component -> hooks/selectors -> service -> API route -> external API
-```
+---
 
-or
+## Phase 1 — Read foundation + UX plan
 
-```text
-page.tsx -> view component -> shared components/dialogs -> service/utils -> local state/auth context
-```
+Read in order:
 
-### 1.3 Reuse hunting via repo-map
+| File | What you extract |
+|------|------------------|
+| `<feature>_UX_PLAN.md` (if present) | Pages, layouts, dialogs, forms, state surface, auth gates, design-system reuse plan |
+| `project-memory/constitution.md` | Non-negotiable rules the plan must honor |
+| `project-memory/architecture.md` | Server/client boundary rules, state-management approach, data-fetching patterns |
+| `project-memory/repo-map.md` | Where pages/views/hooks/services/components live, naming, reusable components |
+| `project-memory/auth-model.md` | Auth context, useAuth, route gating |
+| `project-memory/design-system.md` | Wrappers, form patterns, theme tokens |
+| `project-memory/core-memory.md` | Prior decisions, completed modules |
 
-Before proposing any new file, actively cross-reference `project-memory/repo-map.md` against the feature domain to find reuse candidates. This is the primary reuse check — the repo-map is curated and faster than a broad graph search.
+The UX plan is the **source of truth** for what the feature looks like. Architect's job is to translate it into technical modules that respect the architecture and constitution.
 
-Steps:
+---
 
-1. Re-read the relevant sections of `project-memory/repo-map.md` with the feature in mind (components, hooks, services, utils, types).
-2. List every existing entry that overlaps with what the feature needs.
-3. For each candidate, use `query_graph` (callers_of / callees_of / imports_of) or `get_impact_radius` to understand what it already does and who uses it — confirm it is safe to extend or reuse.
-4. For any proposed new file, write an explicit justification: "checked repo-map sections X and Y; nothing covers this because…". If you cannot write that justification, do not propose the new file.
+## Phase 2 — Map existing code with Serena (≤8 calls)
 
-The goal is that every module in the plan preferentially extends or reuses existing code. New files are the last resort, not the default.
+| Need | Tool |
+|---|---|
+| List symbols in a relevant file | `get_symbols_overview(relative_path="...")` |
+| Find a page / view / hook / service by name | `find_symbol(name_path="...", include_body=false)` |
+| Read a specific symbol body | `find_symbol(name_path="...", include_body=true)` |
+| Trace consumers of a hook/component | `find_referencing_symbols(...)` |
+| Project memories | `list_memories` then `read_memory` if relevant |
 
-### 1.4 Capture existing repo patterns
+Target ≤8 calls. Identify existing pages/views/hooks/services this feature should extend rather than duplicate — feed into the per-module spec.
 
-Document the patterns that the new design must follow:
+---
 
-- Keep `page.tsx` files thin and compositional.
-- Move heavy logic into `src/views/**`, `src/services/**`, `src/hooks/**`, or focused helpers.
-- Prefer shared derivations/selectors over repeated `filter/map/sort` chains.
-- Do not duplicate auth logic or cookie contracts.
-- Respect server/client boundaries between client components, server routes, and secret-bearing code.
-- Tighten service and transform types instead of introducing `any`.
+## Phase 3 — Cross-cutting sub-agent consultations (read-only)
 
-### 1.5 Identify integration points
+For any module touching a cross-cutting concern, consult the sub-agent **as a planning input**. Sub-agents return advice, not code.
 
-For the requested feature, explicitly note:
+Run consultations in parallel where supported (Claude Code Task tool / Cursor subagent background mode).
 
-- Existing files and modules that are closest to the requested behavior
-- Shared services or utilities to reuse
-- Data contracts and types that must be reused or extended
-- API routes or external services that are affected
-- Auth or permission implications
-- Performance-sensitive transforms or rendering paths
-- Whether tests should be unit, integration, manual, or mixed
-- What must be persisted into `project-memory/core-memory.md` after each module lands
+| Concern | Sub-agent to invoke | What you ask for |
+|---|---|---|
+| Private routes, permission-gated UI, useAuth consumers | `/auth-and-permissions` (planning_input mode) | Recommended gate per route, permission key per UI element, useAuth consumers list |
+| Sensitive client-side data (tokens, PII), new third-party scripts, new env-vars | `/security-assessment` (pre-design review) | Risks specific to the proposed surface; constraints the design should respect |
 
-### 1.6 Capture scope decisions
+Parent prompt for sub-agents:
 
-Before designing modules, write down:
+> Sub-agent mode. Proposed module surface from approved UX plan: [excerpt the relevant routes/components/data flows]. Return planning_input JSON per your SKILL.md.
 
-- In scope
-- Out of scope
-- Assumptions
-- Open questions
+Capture each sub-agent's returned JSON. Use it directly in the module specs (Phase 4) — don't paraphrase the specifics away.
 
-If the request is ambiguous, ask clarifying questions before writing the plan.
+If a sub-agent flags a BLOCKER (e.g. fundamental security flaw, no documented auth pattern fits), **stop and surface to the user**. Do not silently adjust the plan around it.
 
 ---
 
-## Phase 2 - Module decomposition
-
-> Goal: split the feature into small modules with clear ownership and dependencies.
-
-### 2.1 Decomposition principles
-
-Apply these rules:
-
-1. Single responsibility per module.
-2. Each module should be mergeable with minimal risk.
-3. Dependencies must be explicit.
-4. Each module should provide testable value.
-5. Prefer smaller modules if a module feels too broad.
-6. Follow existing repo boundaries instead of inventing new layers.
-7. Keep pages thin; avoid modules that push business logic into route/page files.
-8. **Reuse over create**: before proposing a new file, confirm via repo-map.md that nothing equivalent exists. Prefer extending an existing hook, service, or component. A new file must be justified explicitly.
-9. **Deletion safety**: before proposing to delete any file, run `get_impact_radius` on it. List every active caller and dependent. If callers exist, the module must include a migration path for each one before the deletion is permitted. Never propose a deletion without this check.
-
-### 2.2 Valid module shapes in this repo
-
-Common module types for this include:
-
-- Route composition module
-- Feature view/container module
-- Shared component or dialog module
-- Hook/state orchestration module
-- Service/API integration module
-- Shared transform/helper module
-- Auth/permission adjustment module
-- Testing/verification module
-
-Use the smallest combination that fits the actual request.
-
-### 2.3 For each module, define
-
-Every module section in the architecture plan must include these fields. Write them precisely — this content is extracted verbatim into the per-module implementation prompts, so prose rationale and justification notes belong in the architecture plan preamble, not inside the module sections.
-
-| Section | Content |
-|---------|---------|
-| Goal | One-sentence outcome — what the module produces, not why |
-| Depends on | Prior module numbers or `-` |
-| Estimated effort | Rough time range |
-| Key deliverables | Main outcomes as a short bullet list |
-| New files | Table: `File \| Purpose` — one-line purpose per file; repo-map justification as a footnote in the plan, not in the table cell |
-| Changed files | Table: `File \| Anchor symbol \| Exact change` — anchor is the existing function/type/component to locate; exact change is the specific mutation ("add X param", "extend return type with Y", "insert case Z") |
-| Deleted files | Table: `File \| Active callers (get_impact_radius) \| Pre-condition for deletion` |
-| Architecture | Short ASCII diagram for non-trivial call chains only; omit if the file changes are self-explanatory |
-| Contracts | Actual TypeScript — interfaces, function signatures, prop types, route payload shapes. No prose descriptions. |
-| Implementation notes | Module-specific edge cases or constraints only — nothing that restates constitution.md or quality-playbook.md |
-| Auth / permissions | Specific auth implications for this module, or omit if none |
-| Verification | Exact test commands with flags and paths; specific manual steps |
-| Memory update | Exact sentences for core-memory; exact repo-map edits (table rows, section) if this module adds routes/services/patterns |
-
-### 2.4 Use simple architecture diagrams when helpful
-
-Prefer short ASCII diagrams for non-trivial modules.
-
-Examples:
-
-```text
-App Route
-  -> Feature View
-    -> Shared Components
-    -> Hook / selector
-      -> Service
-        -> API route
-          -> External API
-```
+## Phase 4 — Module decomposition
 
-```text
-Dialog UI
-  -> local form state
-  -> submit handler
-    -> service transform
-      -> API request
-        -> response typing
-          -> view refresh
-```
+### 4.1 Decomposition principles
 
----
+1. **Single responsibility** — one module does one thing
+2. **Independent deployability** — a module can ship without breaking what's there
+3. **Explicit dependencies** — if Module B needs Module A, state it
+4. **Incremental value** — each module delivers testable value on its own
+5. **Smallest viable unit** — prefer more smaller modules; >8 hours estimated effort → split it
 
-## Phase 3 - Dependency ordering and implementation sequence
+### 4.2 Typical frontend module shapes
 
-> Goal: produce a safe serial order for implementation.
+For a UI feature, modules often align with layers:
 
-### 3.1 Build the dependency graph
+- **DATA_LAYER / TYPES** — shared types, valibot schemas, API client adapters (if needed)
+- **HOOK_LAYER** — data-fetching hooks, mutation hooks, state hooks
+- **VIEW_LAYER** — composed components (forms, dialogs, drawers) — the bulk of UI code
+- **PAGE_LAYER** — page.tsx files, layout.tsx, route wiring; consumes the views
+- **INTEGRATION** — wiring into nav, breadcrumbs, permission registration
 
-Identify:
+Not every feature needs all five. Use the UX plan to identify the actual layers in play.
 
-- standalone modules that can ship first
-- modules that unblock others
-- modules that should remain behind a flag or guarded rollout
-- modules that should be grouped in one merge because of tight contract coupling
+### 4.3 Per-module fields
 
-### 3.2 Define the implementation order
+For every module, define:
 
-Present the order as a numbered chain, for example:
-
-```text
-1. Shared contracts/helpers
-   |
-2. Service/API integration
-   |
-3. Feature hook/state orchestration
-   |
-4. View/component wiring
-   |
-5. Tests and final verification
-```
+| Field | Content |
+|---|---|
+| **Goal** | One-sentence purpose |
+| **Depends on** | Prerequisite modules (omit if standalone) |
+| **Estimated effort** | Time range (e.g. "4–6 hours") |
+| **Key deliverables** | Files / components / hooks / routes created or modified |
+| **New files** | Table of new files + purpose (omit if none) |
+| **Modified files** | Files this module changes (omit if none) |
+| **Server / client boundary** | Explicit `'use client'` decisions for any new component |
+| **State scope** | For each piece of state: local / hook / context / server |
+| **Data flow** | Server actions vs client fetching vs SWR/React Query — per `architecture.md` |
+| **Core interfaces** | TypeScript types, hook signatures, component prop shapes (text only — no implementation) |
+| **UX plan refs** | Section numbers of `_UX_PLAN.md` this module realizes (so module-runner can read both) |
+| **Auth approach** | From `/auth-and-permissions` sub-agent JSON for this module (if applicable) |
+| **Security considerations** | From `/security-assessment` sub-agent JSON (if applicable) |
+| **Implementation notes** | Patterns, edge cases, things to watch for (re-render, hook deps, focus management) |
+| **Error handling** | Empty/loading/error states per UX plan; error boundary placement |
+| **How to test** | Concrete verification: render test, hook test, integration test, manual UI flow |
 
-### 3.3 Note merge guidance
+### 4.4 Architecture diagrams
 
-Call out:
+For non-trivial modules, ASCII diagrams showing component composition or data flow:
 
-- safe standalone modules
-- coupled modules that should land together
-- risky modules that need extra verification
-- auth-sensitive modules that require `auth-and-permissions`
+```
+┌─────────────────┐    ┌──────────────────┐    ┌───────────────┐
+│ UserListPage    │───▶│ UserListView      │───▶│ useUsersList  │
+│ (server comp)   │    │ (client comp)     │    │ (hook)        │
+└─────────────────┘    └──────────────────┘    └───────────────┘
+                              │
+                              ▼
+                       ┌──────────────────┐
+                       │ EditUserDialog    │
+                       │ (client comp)     │
+                       └──────────────────┘
+```
 
 ---
 
-## Phase 4 - Produce the architecture plan and stop for approval
+## Phase 5 — Dependency ordering
 
-> Goal: create one approved master plan before generating prompts or code.
+### 5.1 Build the dependency graph
 
-### 4.1 Save location
+- Map dependencies between modules
+- Identify standalone modules (ship first)
+- Identify the critical path
 
-Save the master plan to:
+### 5.2 Implementation order
 
-`Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`
+Numbered vertical chain:
 
-### 4.2 Required document structure
+```
+Module 1 — DATA_LAYER (standalone)
+    │
+Module 2 — HOOK_LAYER (depends on M1)
+    │
+Module 3 — VIEW_LAYER (depends on M2)
+    │
+Module 4 — PAGE_LAYER (depends on M3)
+    │
+Module 5 — INTEGRATION (depends on M4)
+```
 
-Use this structure:
+### 5.3 Merge points
 
-```markdown
-# [Feature Name] Architecture Plan
+- Which modules can merge individually (purely additive)?
+- Which must merge together (tightly coupled contract — e.g. types + hook)?
+- Which need a feature flag (visible UI changes)?
 
-[Brief description of the requested enhancement and intended outcome.]
+---
 
-## Scope decisions
+## Phase 6 — Write `_MODULE_WISE_PLAN.md`
 
-### In scope
-- ...
+Save to `documentation/features/<feature_name>/<feature>_MODULE_WISE_PLAN.md`.
 
-### Out of scope
-- ...
+Structure:
 
-### Assumptions
-- ...
+```markdown
+# [Feature Name] — Module-Wise Plan
 
-### Open questions
-- ...
+[One-paragraph description.]
 
-## Memory strategy
+> **Scope decisions (from UX plan §2, confirmed):**
+> - In scope: ...
+> - Out of scope: ...
+> - Assumptions: ...
 
-- Memory document: `project-memory/core-memory.md`
-- What to append after each module:
-  - completed status
-  - files added/changed
-  - key architectural decisions
-  - auth implications
-  - tests run and gaps
-  - notes for the next module
-- Repo map: when the feature adds new API routes, services, hooks, or reusable patterns, update `project-memory/repo-map.md` (tables or placement notes) so the map stays the single source of truth.
+> **UX plan**: documentation/features/<feature_name>/<feature>_UX_PLAN.md
 
-## Relevant codebase study
+---
 
-- `path/to/file` - why it matters
-- `path/to/file` - why it matters
+## Module Overview
 
-## Module overview
+| # | Module | Depends On | Effort | UX plan refs | Key Deliverables |
+|---|--------|-----------|--------|--------------|------------------|
+| 1 | DATA_LAYER | — | X–Y hr | §9 (forms) | types, valibot schemas |
+| 2 | HOOK_LAYER | M1 | X–Y hr | §10 (state) | useUsersList, useUpdateUser |
+| ... | ... | ... | ... | ... | ... |
 
-| # | Module | Depends On | Estimated Effort | Key Deliverables |
-|---|--------|------------|------------------|------------------|
-| 1 | ...    | -          | ...              | ...              |
+---
 
-## Module 1 - [Name]
+## Module 1 — DATA_LAYER
 
-**Goal**: [one sentence — what this module produces]
+**Goal**: ...
 
-**Depends on**: [module numbers or `-`]
+### UX plan references
+- §9 (Forms): Edit user form schema
+- §10 (State): server data shape
 
-**Estimated effort**: ...
+### Auth approach (from /auth-and-permissions consultation)
+[Inline relevant snippet from sub-agent JSON, if applicable]
 
-**Key deliverables**: ...
+### Security considerations (from /security-assessment consultation)
+[Inline relevant snippet, if applicable]
 
-### New files
+### New Files
 | File | Purpose |
 |------|---------|
-| ... | [one-line purpose — repo-map justification as a footnote below this table if needed] |
+| `src/types/user.ts` | shared User type |
+| `src/schemas/user.ts` | valibot schema for EditUserForm |
 
-### Changed files
-| File | Anchor symbol | Exact change |
-|------|---------------|--------------|
-| ... | `existingSymbol` | [specific mutation: "add X param", "extend return type with Y", "insert case Z"] |
+### Server / client boundary
+N/A (pure types/schemas)
 
-### Deleted files
-| File | Active callers (from get_impact_radius) | Pre-condition for deletion |
-|------|-----------------------------------------|---------------------------|
-| ... | none | ... |
-
-### Architecture
-[Short ASCII diagram only if the call chain is non-obvious. Omit if the file changes are self-explanatory.]
-
-### Contracts
-[Actual TypeScript — interfaces, function signatures, prop types, route payloads. No prose.]
-
-```typescript
-// replace with real types for this module
+### Core interfaces
+```ts
+export type User = { id: string; email: string; displayName: string; role: Role; isActive: boolean }
+export const editUserSchema = v.object({...})
 ```
 
 ### Implementation notes
-[Module-specific edge cases or constraints only. Omit anything already covered by constitution.md or quality-playbook.md.]
+...
 
-### Auth / permissions
-[Specific auth implications, or omit if none.]
+### How to test
+- Type check passes (`tsc --noEmit`)
+- Valibot schema accepts/rejects expected inputs (unit test)
 
-### Verification
-- `[exact test command with flags and paths]`
-- Manual: [specific UI action or API call]
+---
 
-### Memory update
-- **core-memory**: [exact sentences to append]
-- **repo-map**: [exact table rows or section edits, or omit if no new routes/services/patterns]
+## Module 2 — HOOK_LAYER
+...
 
-## Implementation order
+---
 
-[dependency chain]
+## Implementation Order
 
-## Merge guidance
+[Dependency chain diagram]
 
+**Recommended merge points:**
 - ...
 
-## Test strategy
-
-- Unit:
-- Integration:
-- Manual:
-
-## Files inventory
+---
 
-| File | Action | Module | Notes |
-|------|--------|--------|-------|
-| ...  | Create | M1 | repo-map justification |
-| ...  | Update | M2 | |
-| ...  | Delete | M3 | callers verified zero via get_impact_radius |
-```
+## Environment / Config Additions
 
-### 4.3 Hard stop
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| ...      | ...     | ...     |
 
-After creating `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`:
+---
 
-- Present the plan to the user.
-- Stop and wait for explicit approval.
-- Do not generate module prompt files yet.
-- Do not write application code yet.
+## Files Inventory
 
-If the user wants changes, update the architecture plan and re-present it.
+| File | Action | Module |
+|------|--------|--------|
+| ...  | Create/Modify | M1 |
+```
 
 ---
 
-## Phase 5 - Generate per-module implementation prompts
+## Phase 7 — Approval gate (HARD STOP)
 
-> Goal: after approval, generate one prompt file per module that a downstream AI can execute safely.
+After writing `_MODULE_WISE_PLAN.md`, **STOP**. Do not generate per-module prompts yet.
 
-### 5.1 Trigger
+Present to user:
+- Path to the plan file
+- One-paragraph summary of the modules
+- Implementation order
+- Any sub-agent findings that materially shaped the plan
+- Pointer back to the UX plan it realizes
 
-Only do this after the user explicitly approves the architecture plan from Phase 4.
+Wait for explicit approval. If user requests changes, update and re-present.
 
-### 5.2 Output files
+---
 
-For each approved module `N`, create:
+## Phase 8 — Generate per-module prompts
 
-`Documentation/features/<feature_name>/MODULE_<N>_<MODULE_NAME>.md`
+Only after explicit user approval.
 
-Example:
+### 8.1 Output files
 
-```text
-Documentation/features/pdf_export_queue/MODULE_1_SHARED_TYPES.md
-Documentation/features/pdf_export_queue/MODULE_2_API_ROUTE.md
-Documentation/features/pdf_export_queue/MODULE_3_QUEUE_WIDGET.md
-Documentation/features/pdf_export_queue/MODULE_4_TESTS.md
+For each module `N`:
+```
+documentation/features/<feature_name>/<feature>_MODULE_<N>_<MODULE_NAME>.md
 ```
 
-### 5.3 Prompt file format
+### 8.2 Per-module prompt template
 
-Each file should follow this format:
+````markdown
+You are implementing **Module <N> — <Module Name>** of the `<feature_name>` feature.
+The master plan was reviewed and approved. Proceed autonomously through all phases.
 
-```markdown
-You are implementing a feature module in the this repo (Next.js App Router, React, TypeScript). Follow this process exactly.
-
-First, read these files in order:
-1. `project-memory/constitution.md`
-2. `project-memory/repo-map.md`
-3. `project-memory/auth-model.md`
-4. `project-memory/quality-playbook.md`
-5. `project-memory/core-memory.md`
-6. `.agent/workflows/build-feature-react.workflow.md`
-7. `.agent/skills/feature-workflow/SKILL.md`
-8. `.agent/templates/FEATURE_PLAN.md`
-9. `.agent/templates/REVIEW_REPORT.md`
-10. `.agent/templates/TEST_PLAN.md`
-11. `Documentation/features/<feature_name>/<FEATURE_NAME>_ARCHITECTURE.md`
-
-Artifact paths for this feature (use these; do not use .agent/plans or .agent/docs):
-- Feature plan: `Documentation/features/<feature_name>/FEATURE_PLAN.md`
-- Test plan: `Documentation/features/<feature_name>/TEST_PLAN.md`
-- Review report: `Documentation/reports/REVIEW_REPORT.md`
-
-Hard rules:
-- No coding before plan approval.
-- Implement only the approved scope for this module.
-- Keep `page.tsx` files thin.
-- Reuse existing auth surfaces; do not create parallel auth logic.
-- Respect server/client boundaries.
-- Reuse shared derivations/helpers instead of duplicating transforms.
-- Before creating any new file, cross-reference `project-memory/repo-map.md` for existing alternatives; only create if none exists and document why.
-- Before deleting any file, run `get_impact_radius` to confirm zero active callers, or execute the migration path specified in the architecture plan before removing the file.
-- After implementation, run `.agent/skills/react-quality-review/SKILL.md` and fix all findings.
-- If the module touches auth-sensitive code or protected routes, also run `.agent/skills/auth-and-permissions/SKILL.md`.
-- Run tests and verification before finalizing: run the test suite (e.g. `npm run test`) for affected areas; fix all failures before updating memory or moving on.
-- Update `project-memory/core-memory.md` after implementing the module and after tests/review are complete.
-- If this module adds new API routes, services, hooks, or reusable patterns, update `project-memory/repo-map.md` (relevant tables or placement notes).
-- Do not finalize development until required tests and verification commands have been run and recorded.
+Execute under the `/module-runner` skill — it owns the per-module lifecycle (implement → build/test/lint → review → fix → security audit → fix → commit → push).
 
 ---
 
-## Module <N> - <Module Name>
+## 1. Relevant context (curated for this module only)
 
-**Goal**: [one sentence — what this module produces]
+### UX plan references
+<Inline the specific UX plan sections this module realizes. Use blockquotes or excerpts. Sections to consider: pages/routes (§6), page layouts (§7), dialogs (§8), forms (§9), state surface (§10), empty/loading/error (§11), a11y (§12), responsive (§13), auth gating (§14).>
 
-**Depends on**: [module numbers or `-`]
-
-### Files to create
-
-| File | Purpose |
-|------|---------|
-| `path/to/new/file.ts` | [what it exports and why no equivalent exists in repo-map] |
+### Repo context (curated from repo-map)
+<Curated repo-map excerpt — see §8.3 curation rules>
 
-### Files to modify
+### Architecture rules (relevant subset)
+<Inline relevant `architecture.md` sections — server/client boundary, state mgmt, data fetching>
 
-| File | Anchor symbol | Exact change |
-|------|---------------|--------------|
-| `path/to/file.ts` | `existingFunctionOrType` | [add / extend / replace — be specific: "add `newParam: Type` to signature", "extend return type with `NewField`", "insert case for `X` in switch"] |
+### Constitution rules (those this module can violate)
+<Inline only the constitution sections relevant to this module>
 
-### Files to delete
+### Design-system patterns to follow
+<Inline the relevant patterns from design-system.md — custom wrappers to use, form pattern, etc.>
 
-| File | Pre-condition |
-|------|--------------|
-| `path/to/file.ts` | [only after callers in `other/file.ts` are migrated to `replacementSymbol`] |
+### Auth approach (from architect's /auth-and-permissions consultation)
+<Inline the endpoint-level auth plan, if applicable>
 
-### Contracts
+### Prior decisions (from core-memory)
+<Inline only entries this module builds on or must not contradict>
 
-[Actual TypeScript — interfaces, function signatures, prop types, route payloads. No prose descriptions — write the real types.]
+---
 
-```typescript
-// example — replace with actual contracts for this module
-export interface ExampleType {
-  id: string;
-  name: string;
-}
+## 2. Module specification
 
-export function exampleFn(id: string): Promise<ExampleType>
-```
+<Full module section copied verbatim from the approved _MODULE_WISE_PLAN.md.
+Omit empty subsections.>
 
-### Data flow
+---
 
-[Short ASCII diagram only if the call chain is non-obvious for this module. Omit if the file changes above make the flow self-evident.]
+## 3. Execution rules
 
-### Auth / permissions
+- No placeholder code. Implement every file in the New Files / Modified Files tables.
+- Honor constitution + design-system rules inlined in §1.
+- Use the documented custom wrappers and form pattern — no raw MUI when a wrapper exists.
+- Use Serena for symbol-level edits where appropriate; raw write for new files.
+- Honor the `'use client'` decisions in §1 — don't add `'use client'` to a server component unintentionally.
+- After implementation, `/module-runner` runs: build + test + lint + `/code-reviewer` + `/security-assessment`. Do not bypass any.
+- After all phases complete, `/module-runner` updates `project-memory/core-memory.md` — you do not.
+````
 
-[Only include if this module touches auth-sensitive code or protected routes. Omit otherwise.]
+### 8.3 Curation rules
 
-### Verification
+1. **Module specification** — copy the module section from `_MODULE_WISE_PLAN.md` verbatim. Omit empty subsections.
 
-- `[exact test command]` — [what it covers]
-- Manual: [specific UI action or API call to confirm the module works end-to-end]
+2. **UX plan references** — quote/excerpt the specific sections (by number) this module realizes. The implementer should not need to read the entire UX plan.
 
-### Memory update
+3. **Curated repo-map context** — only sections this module needs:
 
-- **core-memory**: [exact facts to append — completed status, files added/changed, key decisions, test gaps]
-- **repo-map**: [exact table rows or section edits to add — only if this module introduces new routes, services, hooks, or reusable patterns; omit otherwise]
+   | Always | Conditional |
+   |---|---|
+   | Naming conventions | Pages this module touches |
+   |  | Reusable components this module composes with |
+   |  | Existing hooks this module uses or extends |
 
----
+   Target: ~30–50 lines of focused context.
 
-## Required planning output
+4. **Curated constitution rules** — only sections this module can actually violate:
 
-Fill `Documentation/features/<feature_name>/FEATURE_PLAN.md` with:
-1. Requirement clarification
-2. Codebase study
-3. Detailed plan
-4. Implementation order
+   | Module touches | Include |
+   |---|---|
+   | New pages/routes | Auth/gate rules, validation, error envelope, server/client boundary |
+   | New hooks | Hook rules of React (`react-rules-hooks`), state-derivation rules |
+   | New components | Component-purity rules, rerender-optimization defaults, a11y minimums |
+   | Forms | Form-pattern (react-hook-form + valibot) rules from design-system |
+   | Data fetching | Data-fetching rules from `architecture.md` |
 
-## Quality and testing output
+   Never paste the full constitution.
 
-- Fill `Documentation/reports/REVIEW_REPORT.md`
-- Fill `Documentation/features/<feature_name>/TEST_PLAN.md`
-- Add or update the tests required by this module
-- Run the test suite (e.g. `npm run test`) for affected areas; record commands and results in TEST_PLAN; fix failures before finalizing
-- Append a completed module entry to `project-memory/core-memory.md`
-- If the module added new routes, services, or patterns, update `project-memory/repo-map.md` accordingly
-```
+5. **Design-system inline** — name the specific wrappers and patterns to use; don't make the implementer search the whole guide.
 
-### 5.4 Content rules for module prompt files
+6. **Auth inline** — if `/auth-and-permissions` consultation produced planning JSON for this module, inline it directly. Don't summarize specifics away.
 
-When generating module prompt files, extract only what the implementing agent needs to act — not to understand the architecture decision. Concretely:
+7. **Core-memory inline** — only entries this module depends on or must not contradict.
 
-1. **Goal**: one sentence, outcome-focused. Drop all rationale.
-2. **Files to create**: exact paths only. Drop repo-map justification prose (that was for the architecture review). A one-line purpose is enough.
-3. **Files to modify**: must include the anchor symbol (the existing function, type, or component to locate) and the exact change — "add X", "extend Y to include Z", "replace W with V". Never just "update this file to support the feature."
-4. **Files to delete**: keep only pre-conditions for safe deletion. Drop the impact-radius analysis (already done in the architecture plan).
-5. **Contracts**: write actual TypeScript — interfaces, function signatures, prop types, route payload shapes. Never describe them in prose. These are the authoritative types the agent must implement.
-6. **Data flow**: include only if the call chain across files is non-obvious. A single-file module rarely needs this. Keep it to the specific path for this module, not the whole feature.
-7. **Implementation notes**: omit entirely unless there is a module-specific edge case or constraint that is NOT already covered by `constitution.md` or `quality-playbook.md`. Generic reminders ("keep pages thin", "respect server/client boundary") belong in Hard rules, not here.
-8. **Auth / permissions**: include only if this specific module touches auth-sensitive code. Not a boilerplate flag.
-9. **Verification**: exact commands with flags, not generic `npm run test`. Specify which paths/suites to run.
-10. **Memory update**: exact sentences to append to core-memory and exact repo-map edits (table rows, section placement). No vague "document what changed."
+8. **Replace placeholders** — `<feature_name>`, `<N>`, `<MODULE_NAME>` with actual values.
 
-### 5.5 Confirmation to user
+9. **No code** — the prompt describes what to build, not how to write it.
 
-After generating prompt files, report:
+### 8.4 Confirmation
 
-- all created file paths
-- which module each file covers
-- recommended implementation order
+After generating all prompts, present:
+- List of generated file paths
+- Implementation order
+- Hand-off command: `/module-runner documentation/features/<feature_name>/`
 
 ---
 
 ## Quality gates
 
-Before finalizing the architecture plan, verify:
-
-- [ ] The relevant foundation docs were read first.
-- [ ] Scope, assumptions, and open questions are explicit.
-- [ ] Existing repo patterns were studied before proposing changes.
-- [ ] `project-memory/repo-map.md` was cross-referenced against the feature domain to identify reuse candidates before proposing new files.
-- [ ] Every proposed new file includes an explicit repo-map justification confirming no equivalent exists.
-- [ ] Every proposed deletion has had `get_impact_radius` run; active callers are listed and either zeroed out or a migration path is specified.
-- [ ] Each module has explicit dependencies.
-- [ ] Each module includes verification steps.
-- [ ] Server/client boundaries are respected.
-- [ ] Auth-sensitive work is identified.
-- [ ] Page files remain thin in the proposed design.
-- [ ] Shared derivations/helpers are preferred over duplicate transforms.
-- [ ] The files inventory covers every proposed file change (create, update, delete) with notes.
-- [ ] The implementation order matches the dependency graph.
-- [ ] Each module defines what must be written to `project-memory/core-memory.md`.
-- [ ] When the feature adds new routes, services, or patterns, the plan (or Memory update) states that `project-memory/repo-map.md` must be updated.
+Before finalizing the plan, verify:
 
----
+- [ ] All modules have a clear Goal
+- [ ] Dependencies are explicit and acyclic
+- [ ] Each module has a concrete How-to-test section
+- [ ] No module violates `constitution.md`
+- [ ] Every module references the UX plan sections it realizes (if a UI module)
+- [ ] Modules with auth surfaces have inlined auth approach from sub-agent
+- [ ] Modules with sensitive data have inlined security considerations
+- [ ] Server/client boundaries are explicit per module
+- [ ] State scope decisions match `architecture.md` patterns
+- [ ] Files Inventory covers every change
 
-## Chaining with other skills
+---
 
-This skill designs the implementation. It does not replace the existing execution workflow.
+## Hand-off to `/module-runner`
 
-After planning:
+Plan is ready. Architect's work is done.
 
-1. Use `.agent/skills/feature-workflow/SKILL.md` to implement each approved module.
-2. Use `.agent/skills/auth-and-permissions/SKILL.md` for auth-sensitive modules.
-3. Use `.agent/skills/react-quality-review/SKILL.md` after implementation.
+User runs:
+```
+/module-runner documentation/features/<feature_name>/
+```
 
-The generated module prompts should make downstream implementation safer, smaller in scope, and consistent with the repo's required plan -> approval -> implementation -> review -> test sequence, with `project-memory/core-memory.md` updated after every implemented module.
+`/module-runner` reads each module prompt in order, spawns sub-agents for build/review/security/fix, and commits each module before the next. Architect does not participate in execution.