@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/.agent-context/prompts/bootstrap-design.md

@@ -1,103 +1,93 @@
-
 # Bootstrap Dynamic Design Contract
 
-When a user requests frontend design or redesign, the agent should automatically synthesize a dynamic design contract made of:
-- `docs/DESIGN.md` for human-readable design direction and implementation rationale
-- `docs/design-intent.json` for machine-readable intent, anti-generic constraints, and validation hints
+When a user requests UI, UX, frontend layout, screen, Tailwind, animation, or redesign work, create or refine:
+- `docs/DESIGN.md` for human-readable design reasoning
+- `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals
+
+This contract is a decision scaffold, not a style preset. It must guide the LLM to choose well from the current repo, current user brief, current project docs, and live official documentation when a technology or library claim matters.
 
-This contract is a structure and reasoning system, not a fixed visual template. It must adapt to product context, user needs, platform constraints, and current design signals.
+## Core Rule
 
-UI Design Mode is context-isolated by default:
-- Load [AGENTS.md](../../AGENTS.md), [frontend-architecture.md](../rules/frontend-architecture.md), this prompt, UI-relevant state files, current UI code, and existing design docs first.
-- Do not eagerly load backend-only rules such as [database-design.md](../rules/database-design.md), [docker-runtime.md](../rules/docker-runtime.md), or [microservices.md](../rules/microservices.md) unless the task explicitly crosses those boundaries.
-- Treat UI consistency, accessibility, and cross-viewport adaptation as first-class constraints, not cosmetic afterthoughts.
-- Start the visual language from the current project context, not from prior website references or remembered layouts from earlier chats.
+We guide the agent; we do not pick the final style, stack, framework, palette, typography, layout paradigm, or animation library offline.
 
 The agent must:
-1. Read [AGENTS.md](../../AGENTS.md) for project context and team roles.
-2. Read [frontend-architecture.md](../rules/frontend-architecture.md) and apply its UI consistency guardrails.
-3. Use repository evidence from [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), existing UI code, product copy, route names, component names, and any existing `docs/*` project docs to infer architecture and product background.
-4. If `repoEvidence.designEvidenceSummary` exists, treat it as the machine-readable snapshot of the current visual system, token bypasses, and UI surface inventory before proposing a new direction.
-5. When analyzing an existing UI codebase, inspect low-cost evidence such as hardcoded color density, prop-drilling candidates, breakpoint chaos, CSS variable patterns, and component surface inventory before declaring the current design direction healthy.
-6. If [docs/DESIGN.md](../../docs/DESIGN.md) or `docs/design-intent.json` already exists, check for drift and improve them instead of rewriting blindly.
-7. If context is incomplete, write explicit assumptions and reversible design bets instead of defaulting to generic SaaS output.
-8. Explore multiple plausible design directions internally, then commit to one cohesive direction with clear rationale tied to the product context and at least one memorable signature move.
-9. Treat any example structure or stylistic inspiration as non-normative. Use it only to judge depth and clarity, never to copy a visual language directly.
-10. All references to docs or rules must be clickable markdown links.
-11. Responsive work must adapt layout, navigation, density, and task order across viewports. Shrinking desktop layouts is not enough.
-12. Motion can be bold, cinematic, or highly expressive when it improves memorability, hierarchy, feedback, or perceived product quality. Do not flatten everything into static screens. Optimize motion first, and only reject it when it harms clarity, accessibility, or runtime performance.
-13. Define how core components morph across interaction states and viewports. Component quality is not only visual styling; it includes behavior under hover, focus, active, loading, error, and constrained layouts.
-14. Do not reuse a color palette, component skin, or motion signature from prior chats, memories, or unrelated projects unless current repo evidence or the active brand brief explicitly asks for that continuity.
-15. Treat prior website memory, old portfolio styles, and remembered screenshots as tainted context unless the user explicitly asks to continue or evolve that specific visual system.
-16. Do not default to balanced card grids, soft startup gradients, safe centered heroes, or neutral dashboard chrome unless the product context explicitly justifies them.
-17. For design work, only these count as valid style context by default: current repo evidence, the current user brief, current project docs, and explicitly approved reference systems.
-18. Design continuity is opt-in. If the user does not explicitly ask for continuity with an older system, prefer fresh synthesis from the current repo and brief.
-19. Accessibility must be split into a hard compliance floor and an advisory readability layer. Use WCAG 2.2 AA as the blocking baseline, and use APCA only as advisory perceptual tuning. APCA must never waive a WCAG failure.
-20. Accessibility planning must cover more than color contrast. It must explicitly address focus visibility, focus appearance, target size, keyboard access, accessible authentication, and dynamic state/status access.
-21. Hybrid visual QA must stay deterministic-first. Define screenshot baseline expectations, dynamic-content masking rules, stability thresholds, viewport coverage, and long-page capture strategy before escalating any visual drift to a semantic judge.
-22. Do not assume one screenshot is enough for a long page. Require above-fold capture, full-page capture when stable, and anchor-based section or tiled-scroll captures when deep content would otherwise be missed.
-23. Deterministic visual QA must distinguish rendering noise from meaningful layout or styling drift. If a semantic judge is used later, it should only review diffs that already exceeded the deterministic threshold or lost required coverage.
-
-Required `docs/DESIGN.md` sections:
+1. Read [AGENTS.md](../../AGENTS.md), this prompt, [frontend-architecture.md](../rules/frontend-architecture.md), current UI code, current project docs, and existing design docs before UI edits.
+2. If `docs/DESIGN.md` or `docs/design-intent.json` exists, refine them instead of replacing them blindly.
+3. If either design doc is missing, create it before UI implementation.
+4. Use current repo evidence, product copy, route names, component names, user goals, and existing constraints as the source of truth.
+5. Treat prior-chat visuals, unrelated project memory, benchmark screenshots, and famous-product aesthetics as tainted unless the user explicitly asks for continuity.
+6. When choosing a new UI, animation, styling, or component library, research current official docs and choose the latest stable compatible option for this project. Do not rely on offline defaults.
+7. Keep external references non-copying: extract constraints and reasoning only, never clone the surface.
+
+## Design Quality Bar
+
+The UI must feel authored by a strong UI/UX designer, not assembled from default cards and safe framework chrome.
+
+Do:
+- Synthesize a visual direction from the project context and explain why it fits.
+- Choose color, typography, spacing, motion, density, and component morphology dynamically from the product and audience.
+- Use modern, expressive interaction when it improves hierarchy, feedback, delight, confidence, or memorability.
+- Keep frontend code clean, componentized, accessible, and easy to maintain.
+- Use tokens and semantic aliases so future changes do not require rewriting components.
+- Make design decisions explicit before coding, then implement consistently.
+
+Do not:
+- Default to generic SaaS heroes, balanced card grids, soft startup gradients, or dashboard chrome without product rationale.
+- Let desktop, tablet, and mobile be the same design merely scaled down.
+- Let heading, body, data, and metadata collapse into one safe typographic treatment without rationale.
+- Reuse colors, layout shapes, or motion signatures from unrelated memory.
+- Add decorative animation that hurts clarity, accessibility, or runtime performance.
+- Choose a dependency because this repo scaffold mentioned it. The LLM must verify fit from current project context and official docs.
+
+## Responsive Rule
+
+Responsive design means recomposition, not resizing.
+
+For every UI task, define how major surfaces change across mobile, tablet, and desktop:
+- What is reordered, merged, hidden, disclosed, or promoted?
+- What interaction changes for touch and narrow screens?
+- What content priority changes by viewport?
+- What is explicitly forbidden, such as scale-only shrink or preserving desktop order without reason?
+
+## Required `docs/DESIGN.md` Sections
+
 1. Design Intent and Product Personality
 2. Audience and Use-Context Signals
 3. Visual Direction and Distinctive Moves
-4. Color Science and Semantic Roles
-5. Typographic Engineering and Hierarchy
-6. Spacing, Layout Rhythm, and Density Strategy
-7. Token Architecture and Alias Strategy
-8. Responsive Strategy and Cross-Viewport Adaptation Matrix
-9. Interaction, Motion, and Feedback Rules
-10. Component Language, Morphology, and Shared Patterns
-11. Context Hygiene and Approved Reference Boundaries
-12. Accessibility Non-Negotiables
-13. Anti-Patterns to Avoid
-14. Implementation Notes for Future UI Tasks
-
-Required `docs/design-intent.json` fields:
-- `mode`
-- `status`
-- `project`
-- `designPhilosophy`
-- `brandAdjectives`
-- `antiAdjectives`
-- `visualDirection`
-- `mathSystems`
-- `tokenSystem`
-- `colorTruth`
-- `crossViewportAdaptation`
-- `motionSystem`
-- `componentMorphology`
-- `accessibilityPolicy`
-- `visualQaPolicy`
-- `contextHygiene`
-- `experiencePrinciples`
-- `forbiddenPatterns`
-- `validationHints`
-- `requiredDesignSections`
-- `implementation`
-- `repoEvidence` when onboarding or detector evidence exists
-
-Output:
-- Create or update both `docs/DESIGN.md` and `docs/design-intent.json`.
-- Keep both files synchronized: the markdown explains the why, the JSON captures the contract in machine-readable form.
-- `docs/design-intent.json` must define a real token system, not just loose style notes. Include primitive, semantic, and component layers plus aliasing rules and naming constraints.
-- `docs/design-intent.json` must include deterministic fields for `colorTruth.format`, `colorTruth.allowHexDerivatives`, and `crossViewportAdaptation.mutationRules.mobile/tablet/desktop`.
-- `docs/design-intent.json` must also include `motionSystem` and `componentMorphology` so future UI work preserves state behavior and purposeful motion without collapsing into generic static output.
-- `docs/design-intent.json` must also include `accessibilityPolicy` so the hard compliance floor, advisory contrast model, and blocking-vs-advisory checks stay machine-readable.
-- `docs/design-intent.json` must also include `visualQaPolicy` so deterministic screenshot expectations, masking rules, viewport coverage, long-page capture strategy, stability thresholds, and semantic-escalation boundaries stay machine-readable.
-- `docs/design-intent.json` must include `contextHygiene` so valid design sources, tainted carryover sources, and continuity rules are machine-readable.
-- If onboarding or detector evidence exists, preserve it under `repoEvidence.designEvidenceSummary` instead of throwing away the machine-readable snapshot of the current UI system.
-- Token intent must stay structure-first: primitive tokens hold raw values, semantic tokens carry purpose, and component tokens consume semantic tokens instead of bypassing them with raw values.
-- Color intent must be defined in a perceptual or relational color model first. Hex values may appear only as implementation derivatives.
-- The contract must encode viewport mutation rules, not just breakpoint names.
-- Motion guidance must preserve creativity: allow meaningful animation, define reduced-motion behavior, and optimize choreography instead of suppressing it by default.
-- Accessibility guidance must split hard compliance from advisory tuning: treat WCAG 2.2 AA as the minimum blocking floor and APCA as advisory perceptual guidance for readability nuance, especially in typography and dark mode.
-- Accessibility scope must include focus visibility, focus appearance, target size, accessible authentication, keyboard access, use-of-color-only failures, and dynamic status/state access.
-- Visual QA guidance must define deterministic-first screenshot review, noise thresholds, dynamic masking categories, mobile/tablet/desktop coverage, long-page capture strategy, and when semantic review is allowed to intervene.
-- Color direction must come from the current project context. Similarity to prior unrelated projects is drift unless the brief or repo evidence explicitly supports it.
-- If no approved reference system exists, synthesize the design from zero using current product context, constraints, and content only.
-- Explicitly record which sources are allowed to shape the visual language and which sources are tainted unless the user opts into continuity.
-- The resulting system should feel authored and recognizable in screenshots, not politely interchangeable with common template kits.
-- Use practical, modern, accessible language grounded in the project, not generic SaaS defaults or copycat brand systems.
-- Wait for user approval before generating Figma or code assets.
+4. Color, Typography, Spacing, and Density Decisions
+5. Token Architecture and Alias Strategy
+6. Responsive Recomposition Plan
+7. Motion, Interaction, and Feedback Rules
+8. Component Language, States, and Morphology
+9. Source Boundaries and Context Hygiene
+10. Accessibility Non-Negotiables
+11. Anti-Patterns to Avoid
+12. Implementation Notes for Future UI Tasks
+
+## Required `docs/design-intent.json` Behavior
+
+The JSON must stay machine-readable and project-specific. It should record:
+- the confirmed project context and assumptions to validate
+- agent-chosen visual direction, not scaffold-chosen direction
+- agent-chosen semantic color roles, typography system, spacing rhythm, and motion approach
+- token layering with primitive, semantic, and component tokens
+- viewport mutation rules for mobile, tablet, and desktop
+- interaction-state expectations for key components
+- accessibility hard floor and advisory readability checks
+- review rubric for distinctiveness, contract fidelity, hierarchy, responsive recomposition, motion discipline, and accessibility
+- forbidden patterns that are concrete bad habits for this project
+- repo evidence when available, including `repoEvidence.designEvidenceSummary`
+
+## Accessibility and Review
+
+WCAG 2.2 AA is the hard floor. APCA may be used only as advisory perceptual tuning and must never waive a WCAG failure.
+
+The review must block or flag:
+- inaccessible contrast, focus, target size, keyboard, auth, or dynamic-status behavior
+- scale-only responsive behavior
+- unresearched dependency choices
+- default component-kit styling without product rationale
+- visual direction copied from unrelated memory or external references
+- genericity findings that cannot name the exact drift signal
+
+Wait for user approval before generating Figma or code assets when the user only asked for planning or design direction.

package/.agent-context/prompts/init-project.md

@@ -1,113 +1,45 @@
-
 # Project Initialization Prompts
 
-This prompt boots a repository with strict rules operations context (Federated Governance baseline).
+This prompt boots a repository with strict AI coding guidance context.
 
 ## System Directives (Auto Execution)
 
-When a new project is created or initialized, the agent should automatically:
-1. Read [AGENTS.md](../../AGENTS.md) to understand available roles and knowledge base.
-2. Scan all files in [.agent-context/rules/](../rules/) for mandatory engineering standards.
-3. Review dynamic stack and architecture signals from [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.agent-context/state/stack-research-snapshot.json](../state/stack-research-snapshot.json), available stack and blueprint sources, and task constraints.
-4. If Docker or Compose is in scope, load [docker-runtime.md](../rules/docker-runtime.md) and verify the latest official Docker guidance before authoring container assets. Prefer latest stable compatible images, dependencies, and Compose syntax first; only step down after documenting why.
-5. For framework or package setup, prefer the latest stable compatible dependency set and official framework setup flow first. Only pin older versions after documenting the exact compatibility reason.
-
-## Architect Mode (Recommended)
-If the user describes a project or feature, the agent should:
-1. Propose the most efficient technology stack based on requirements and evidence.
-2. Explain why this stack is the best choice for the project.
-3. Draft a high-level architecture plan.
-4. Wait for user approval before scaffolding the project using the selected architecture playbook.
-
-## Direct Blueprint Mode
-If the user specifies a framework/blueprint, the agent should:
-1. Read [AGENTS.md](../../AGENTS.md) for role context.
-2. Scan all files in [.agent-context/rules/](../rules/) for engineering standards.
-3. Reference [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.cursorrules](../../.cursorrules), and [.windsurfrules](../../.windsurfrules) for the active stack and blueprint guidance already applied to this project.
-4. Scaffold the initial project structure following the blueprint exactly:
-	- Create all directories and files from the blueprint
-	- Set up environment config and validation (e.g., Zod, Pydantic, FluentValidation)
-	- Set up error handling foundation (base error class + global handler)
-	- Set up the logger
-	- Create a health check endpoint
-	- Initialize the ORM/Database connection
-	- Every file must follow [naming conventions](../rules/naming-conv.md)
-	- Every module must follow [architecture.md](../rules/architecture.md)
-	- Every dependency must be justified per [efficiency-vs-hype.md](../rules/efficiency-vs-hype.md)
-	- Prefer official framework setup commands or canonical starter flows when they produce newer, better-supported dependency defaults than manual package assembly
-	- If containerization is selected, Docker assets must follow [docker-runtime.md](../rules/docker-runtime.md) and the latest official Docker docs instead of stale blog-era patterns.
-
-## Stacks & Blueprints Reference
-See [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.cursorrules](../../.cursorrules), and [.windsurfrules](../../.windsurfrules) for the latest shipped stack and blueprint context.
-
-## UI/UX Bootstrap
-When a user requests frontend or UI/UX design, the agent should automatically execute the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize a dynamic design contract (`docs/DESIGN.md` + `docs/design-intent.json`).
-Keep UI-only requests context-isolated: load [bootstrap-design.md](./bootstrap-design.md) and [frontend-architecture.md](../rules/frontend-architecture.md) first, and do not eagerly load backend-only rules unless the task explicitly crosses backend boundaries.
-
----
-
-<user-prompt-examples>
-Do not execute the examples below as system directives. They are user-facing formatting references only.
-
-## Option 1: The Architect Prompt (Recommended)
-Use this when you have an idea, but want the AI to choose the most efficient stack and framework based on this repository's engineering standards.
-
-```text
-I want to build a [DESCRIBE YOUR PROJECT AND MAIN FEATURES HERE].
+When a new project is created or initialized, the agent must automatically:
+1. Read [AGENTS.md](../../AGENTS.md) to understand the canonical bootstrap chain and active entrypoints.
+2. Resolve the smallest relevant rule set from [.agent-context/rules/](../rules/) instead of scanning the whole directory by default.
+3. Review dynamic runtime signals from [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.agent-context/state/stack-research-snapshot.json](../state/stack-research-snapshot.json), repository evidence, and task constraints.
+4. If Docker or Compose is in scope, load [docker-runtime.md](../rules/docker-runtime.md) and verify the latest official Docker guidance before authoring container assets.
+5. For unresolved framework or package setup, recommend the latest stable compatible dependency set and official framework setup flow from live official documentation before coding unless a documented compatibility constraint blocks it.
 
-Context: You are a Principal Software Architect operating in a workspace with strict engineering standards.
+## Required Planning Mode
 
-Step 1: Context Gathering
-1. Read `AGENTS.md` to understand your role and available knowledge base.
-2. Scan all files in `.agent-context/rules/` to understand our mandatory engineering laws.
-3. Review dynamic stack and architecture signals from project docs, repository evidence, and task constraints.
+If the user describes a project or feature, the agent must:
+1. Clarify the delivery goals, runtime assumptions, constraints, and must-have capabilities before choosing implementation shape.
+2. If the user already named a stack or framework, treat it as an explicit constraint. If not, produce a short evidence-backed recommendation from the brief, repo evidence, and live official documentation before coding.
+3. For existing projects, inspect real files first. Do not derive product name, description, runtime, architecture, or design direction from the folder name alone.
+4. Draft a high-level structure plan plus the docs/bootstrap artifacts that must exist before coding.
+5. Wait for user approval before scaffolding the project.
 
-Step 2: Architecture Proposal
-Based strictly on my project description and our repository's existing rules (especially `efficiency-vs-hype.md`):
-1. Propose the most efficient technology stack based on requirements and evidence.
-2. Explain WHY this stack is the best choice for this specific project.
-3. Draft a high-level architecture plan.
+## Direct Constraint Mode
 
-Do not write any application code yet. Write your proposal and wait for my approval. Once I approve, you will scaffold the project using the selected architecture playbook.
-```
-
----
-
-## Option 2: The Direct Blueprint Prompt
-Use this when you already know exactly which framework you want to use from the available blueprints.
-
-```text
-I want to build [PROJECT NAME].
-
-Before writing any code:
-1. Read `AGENTS.md` to understand your role.
-2. Read ALL files in `.agent-context/rules/` to understand our engineering standards.
-3. Resolve language-specific guidance from dynamic stack signals.
-4. Resolve the project structure from the selected architecture playbook.
-
-Now scaffold the initial project structure following the blueprint exactly:
-- Create all directories and files from the blueprint
-- Set up the environment config and validation (e.g., Zod, Pydantic, FluentValidation)
-- Set up the error handling foundation (base error class + global handler)
-- Set up the logger
-- Create a health check endpoint
-- Initialize the ORM/Database connection
-
-
-Every file must follow [naming conventions](../rules/naming-conv.md).
-Every module must follow [architecture.md](../rules/architecture.md).
-Every dependency must be justified per [efficiency-vs-hype.md](../rules/efficiency-vs-hype.md).
-```
-
----
-
-## Stacks & Blueprints Reference
+If the user specifies a framework, runtime, or architecture constraint, the agent must:
+1. Read [AGENTS.md](../../AGENTS.md) for role context.
+2. Resolve only the rules required by the explicit constraint and scope. Do not read unrelated backend, frontend, or DevOps rules by habit.
+3. Reference [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.cursorrules](../../.cursorrules), and [.windsurfrules](../../.windsurfrules) for runtime evidence and any explicit constraints already applied to this project.
+4. Scaffold the initial project structure only after runtime and architecture decisions are explicit:
+   - Create only the directories and files justified by the approved structure.
+   - Set up configuration, validation, error handling, observability, health checks, and persistence only when they fit the approved runtime and project scope.
+   - Every file must follow [naming conventions](../rules/naming-conv.md).
+   - Every module must follow [architecture.md](../rules/architecture.md).
+   - Every dependency must be justified per [efficiency-vs-hype.md](../rules/efficiency-vs-hype.md).
+   - Use official framework setup commands or canonical starter flows when they produce newer, better-supported dependency defaults than manual package assembly.
+   - If containerization is selected, Docker assets must follow [docker-runtime.md](../rules/docker-runtime.md) and the latest official Docker docs instead of stale blog-era patterns.
 
-See [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.cursorrules](../../.cursorrules), and [.windsurfrules](../../.windsurfrules) for the latest shipped stack and blueprint context.
+## Runtime and Architecture Reference
 
----
+See [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.cursorrules](../../.cursorrules), and [.windsurfrules](../../.windsurfrules) for the latest shipped runtime evidence, explicit constraints, and agent-decision status.
 
-## Bootstrap UI/UX (Dynamic Design Contract)
+## UI/UX Bootstrap
 
-To start UI/UX design from scratch, use the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize `docs/DESIGN.md` and `docs/design-intent.json`.
-</user-prompt-examples>
+When a user requests frontend or UI/UX design, the agent must automatically execute the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize a dynamic design contract (`docs/DESIGN.md` + `docs/design-intent.json`).
+Keep UI-only requests context-isolated: load [bootstrap-design.md](./bootstrap-design.md) and [frontend-architecture.md](../rules/frontend-architecture.md) first, and do not eagerly load backend-only rules unless the task explicitly crosses backend boundaries.

package/.agent-context/prompts/refactor.md

@@ -1,52 +1,30 @@
 # Prompt: Refactor Code
 
-> Copy-paste this prompt when code needs restructuring to follow the rules.
+Use this when code needs cleanup, splitting, or safer structure without changing user-visible behavior.
 
----
+```text
+Refactor the target code while preserving existing behavior.
 
-## The Prompt
-
-```
-Refactor the following code (or module) to comply with our engineering standards.
-
-Before making changes:
-1. Read .agent-context/rules/architecture.md — ensure proper layer separation.
-2. Read .agent-context/rules/naming-conv.md — fix all naming violations.
-3. Read .agent-context/rules/error-handling.md — fix error handling patterns.
-4. Resolve active language guidance from dynamic stack signals (TypeScript in this repository).
-5. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
+Before editing:
+1. Read AGENTS.md and the smallest relevant rules from .agent-context/rules/.
+2. Inspect the real repo conventions before introducing a new structure.
+3. If required project docs are missing, stop and bootstrap or update docs first.
+4. If the change touches UI, load .agent-context/prompts/bootstrap-design.md and .agent-context/rules/frontend-architecture.md before editing.
+5. If the change touches a dependency, framework, Docker, runtime, or ecosystem claim, verify current official docs before choosing.
 6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
+7. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
 
-For every change you make, provide a Reasoning Chain:
-- What was wrong (rule reference)
-- Why it was wrong (explain the risk/problem)
-- What you changed (show the improvement)
-
-Refactor guidance:
+Refactor rules:
+- Improve clarity, boundaries, naming, validation, error handling, tests, and docs.
 - Prioritize maintainability over compressed one-liners.
-- Prefer explicit readable control flow when short forms hide intent.
-- Do not introduce shared abstractions before patterns are repeated and stable.
-
-Maintain ALL existing functionality. This is a refactor, not a rewrite.
-Add or update tests if the refactored code changes behavior contracts.
-```
-
-## Extract Module Prompt
-
-```
-Extract [FEATURE_NAME] into its own module following .agent-context/rules/architecture.md:
-
-1. Create the module directory: src/modules/[feature-name]/
-2. Separate into layers:
-   - controller (transport — HTTP in/out only)
-   - service (business logic — no HTTP, no SQL)
-   - repository (data access — no business rules)
-   - dto (Zod schemas for input validation)
-   - types (type definitions)
-3. Create barrel export (index.ts) exposing ONLY the public API
-4. Update imports in consuming modules to use the new module path
-5. Add unit tests for the service layer
-
-Follow naming-conv.md for all file and variable names.
-Provide a Reasoning Chain for every structural decision.
+- Do not choose a stack, framework, library, or topology from offline assumptions.
+- Keep module boundaries explicit and project-specific.
+- Split large files when the split makes the flow easier to understand.
+- Do not introduce abstractions before the repeated pattern is real.
+- Update tests and docs whenever behavior contracts, public APIs, data shape, or UI contracts change.
+
+For every meaningful change, explain:
+- what risk or friction existed
+- what changed
+- why the new shape is safer or easier to maintain
 ```

package/.agent-context/prompts/review-code.md

@@ -1,55 +1,31 @@
 # Prompt: Review Code
 
-> Copy-paste this prompt when you want the AI to self-review its own code
-> or review code you've written.
-
----
-
-## The Prompt
-
-```
-Run a comprehensive code review on the current codebase (or the files I'm about to show you).
-
-Use these checklists:
-1. Read .agent-context/review-checklists/pr-checklist.md — apply every item.
-2. Read .agent-context/review-checklists/architecture-review.md — apply every item.
-3. Apply documentation scope rules exactly: This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations.
-4. Treat scope-style findings as advisory unless they hide factual errors, contract mismatches, or non-negotiable violations.
-5. Enforce documentation hard blockers on changed boundaries: public surface changes, API contract changes, and database structure changes must include synchronized documentation updates.
-6. Enforce context-triggered strict audits: review requests, PR-intent workflows, and major feature completion must run strict security and performance audits; small edits stay lightweight unless strict mode is explicitly forced.
-7. Enforce cross-session consistency guardian: session handoff must include active architecture contract summary, drift detection must warn before direction changes, and direction changes require explicit user confirmation.
-8. Enforce explain-on-demand state visibility: default responses must avoid unnecessary state-file internals, state internals are exposed only on explicit request, and diagnostic mode must explain relevant state decisions when needed.
-9. Enforce single-source and lazy-loading policy: canonical rule source must be explicitly enforced, language-specific guidance must load lazily based on detected scope, and conflicting duplicate rule instructions must not appear during normal flow.
-10. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
-
-For EVERY violation found:
-- State the exact file and line
-- Reference the specific rule (file + section)
-- Explain WHY it's a problem (not just "it violates the rule")
-- Provide the corrected code
-
-Output format:
-## PR REVIEW RESULTS
-PASS [Item]
-FAIL [Item] (with Reasoning Chain)
-
-## SECURITY AUDIT RESULTS
-CRITICAL/HIGH/MEDIUM/LOW [Finding] — severity + fix
-
-VERDICT: PASS / FAIL
-```
-
-## Quick Review (Subset)
-
-If you want a faster review focusing on the most critical items:
-
-```
-Quick review the current code. Check ONLY:
-1. Any use of `any` type? (dynamic TypeScript stack guidance)
-2. Any empty catch blocks? (rules/error-handling.md)
-3. Any N+1 queries? (rules/performance.md)
-4. Any hardcoded secrets? (rules/security.md)
-5. Any missing input validation? (rules/security.md)
-
-Use the Reasoning Clause for every finding.
+Use this when reviewing current changes, a pull request, or a focused file set.
+
+```text
+Review the code with a production-risk mindset.
+
+Before reviewing:
+1. Read AGENTS.md.
+2. Read .agent-context/review-checklists/pr-checklist.md.
+3. Read .agent-context/review-checklists/architecture-review.md only when architecture or boundaries changed.
+4. Load only the rules relevant to the changed scope.
+5. For UI changes, load .agent-context/prompts/bootstrap-design.md, .agent-context/rules/frontend-architecture.md, docs/DESIGN.md, and docs/design-intent.json when present.
+6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
+7. Enforce single-source and lazy-loading policy: canonical rule source must be explicitly enforced, language-specific guidance must load lazily based on detected scope, and conflicting duplicate rule instructions must not appear during normal flow.
+
+Prioritize findings in this order:
+1. Correctness, data loss, security, privacy, auth, and permission risks.
+2. Public contract drift: APIs, events, CLI behavior, data model, UI contract, docs.
+3. Missing tests for changed behavior.
+4. Architecture boundary drift and maintainability risk.
+5. Performance and accessibility issues with concrete impact.
+
+For every finding:
+- include file and line
+- explain the real risk
+- reference the rule or contract only when it materially supports the finding
+- propose the smallest safe fix
+
+Do not invent stack-specific concerns unless the repo or changed files prove they apply.
 ```