@ryuenn3123/agentic-senior-core 3.0.45 → 3.0.47

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

@@ -5,7 +5,6 @@ Use this prompt for UI, UX, frontend layout, screen, Tailwind, animation, 3D, ca
 Create or refine `docs/DESIGN.md` for human reasoning and `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals.
 
 This contract is a decision scaffold, not a style preset. We guide the agent; we do not pick the final style, stack, framework, palette, typography, layout paradigm, or animation library offline.
-
 ## Authority
 - Treat `.agent-context/` and current project docs as technical authority.
 - Treat `README.md` as public and developer overview, setup, usage, and user-facing context only. Do not use it as coding, architecture, or design authority when `.agent-context/` gives a stricter rule.
@@ -13,7 +12,6 @@ This contract is a decision scaffold, not a style preset. We guide the agent; we
 - Treat prior-chat visuals, unrelated project memory, benchmark screenshots, and famous-product aesthetics as tainted context unless the user explicitly approves continuity.
 - Keep external references non-copying; extract constraints only.
 - Before choosing a new UI, animation, scroll, 3D, canvas, chart, icon, styling, or component library, research current official docs.
-
 ## Required Order
 1. Read `AGENTS.md`, this prompt, `../rules/frontend-architecture.md`, current UI code, current project docs, and existing design docs.
 2. Refine existing `docs/DESIGN.md` and `docs/design-intent.json`; do not replace them blindly.
@@ -21,7 +19,6 @@ This contract is a decision scaffold, not a style preset. We guide the agent; we
 4. Record `motionPaletteDecision` before UI code; product categories are heuristics, not style presets.
 5. Encode `repoEvidence.designEvidenceSummary` when onboarding or detector evidence exists.
 6. Keep both design docs synchronized after implementation.
-
 ## Creative Commitment Gate
 Before broad compliance review or UI implementation, record an agent-chosen visual direction in both design docs:
 - one concrete real-world anchor reference
@@ -30,7 +27,6 @@ Before broad compliance review or UI implementation, record an agent-chosen visu
 - one authored visual bet visible in the first viewport
 
 Reject generic anchors. Do not accept "modern", "clean", "premium", "expressive", "minimal", or "bold" as the anchor. Name a material, instrument, artifact class, architectural system, editorial genre, cinematic behavior, exhibition system, scientific apparatus, or industrial mechanism.
-
 ## Dynamic Avant-Garde Anchor Engine
 If no current-task research or visual reference exists, activate the Dynamic Avant-Garde Anchor Engine before coding.
 
@@ -40,10 +36,11 @@ Rules:
 - Discard the two safest or most predictable options.
 - Output only the chosen anchor, specific reference point, and rationale.
 - Forbid final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.
+- Do not default to spatial place metaphors such as room, darkroom, control room, counting room, war room, studio, lab, cockpit, or command center. Use them only when the product truly depends on a physical place model.
+- Prefer artifacts, custody flows, instruments, data behaviors, materials, editorial systems, service rituals, or interaction mechanisms over "where the interface lives" as the anchor.
 - Derive typography, spacing, density, color behavior, morphology, motion, and responsive composition from the chosen anchor.
 - Translate the anchor non-literally first. Anchor artifacts are evidence for behavior, hierarchy, density, typography, state language, and motion, not automatic UI chrome.
 - Use reduced-motion fallbacks instead of suppressing motion.
-
 ## Creative Ambition Floor
 Before UI code, record:
 - one product-derived palette move
@@ -52,19 +49,18 @@ Before UI code, record:
 - at least three at-a-glance product-specific signals for new screens or broad redesigns
 
 Do not ship AI-safe UI. Record exact drift signals in `reviewRubric`; at minimum reject decorative grid wallpaper, default line backgrounds, calibration-mark wallpaper, soft glow backgrounds, generic abstract marks, testing/demo/placeholder UI copy, terminal-only user flows, and first-output composition with only local copy swapped in when they have no product function. Treat measurement, calibration, crop, route, timeline, and inspection marks as task overlays or control affordances only; never promote them to the page background, hero backdrop, or first-output visual texture. If a conceptual anchor suggests a forbidden motif, the forbidden motif wins; express the anchor through workflow, hierarchy, density, typography, material behavior, state design, and interaction grammar instead of literal wallpaper.
-
 ## Brave Redesign Default
 For UI design work, the agent owns the ambition decision. For broad screens, redesigns, or new visual systems, treat expressive motion, spatial hierarchy, distinctive composition, and product-specific interaction as the baseline even when the user did not say "rich". Do not reduce the request to a safer version of the existing UI, a static implementation, or a component-kit rearrangement because research or dependency selection feels inconvenient.
 
 If the expressive path needs a new motion, 3D, canvas, scroll, or interaction library and web search is available, perform the official-doc research and record the decision. If web search is unavailable, use already-present dependencies or native browser capabilities while preserving the intended ambition, then mark library verification as pending.
 
 Only downshift ambition after naming the concrete blocker: product fit, content density, measured performance budget, accessibility, device support, package conflict, security risk, or missing runtime capability. A new dependency, package count, or vague performance concern is not a blocker by itself. Pair every downshift with a replacement interaction quality that still changes composition, hierarchy, feedback, or memorability.
-
 ## Design Flexibility Layer
-
 `docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it.
 
-Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, and literal anchor artifacts flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked. Required experience outcomes are separate from candidate implementation moves. Libraries supply behavior, accessibility, primitives, and delivery speed; the project supplies final composition, theme, morphology, and visual language.
+Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked. Required experience outcomes are separate from candidate implementation moves. Libraries supply behavior, accessibility, primitives, and delivery speed; the project supplies final composition, theme, morphology, and visual language.
+## External Inspiration Boundary
+Using outside websites, benchmark apps, galleries, or component examples is useful for constraint discovery, interaction mechanics, and implementation options, but never as a style source to imitate. Extract why a pattern works, then translate it into a current-project rule. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture from a reference unless the user explicitly approves that continuity and it passes product fit.
 
 ## AI Color and Template Residue Audit
 AI color drift happens when a palette uses safe defaults before product meaning.
@@ -108,8 +104,12 @@ If web search is unavailable:
 - Use native CSS, browser APIs, or already-present dependencies.
 - Set `libraryResearchStatus` to `pending-verification`.
 
-Treat unresearched dependency choices as review findings. Dynamic UI Foundation Selection: do not default to shadcn/ui, Tailwind-only, native-only, or any component kit because it is familiar. Choose the foundation from product type, interaction complexity, accessibility needs, design ambition, team/runtime constraints, bundle/runtime cost, and current official docs.
+Treat unresearched dependency choices as review findings. Dynamic UI Foundation Selection: do not default to shadcn/ui, Tailwind-only, native-only, or any component kit because it is familiar, and do not avoid them because a guardrail exists. Choose the foundation from product type, interaction complexity, accessibility needs, design ambition, team/runtime constraints, bundle/runtime cost, and current official docs.
 Ready-made primitives are allowed when they improve behavior, accessibility, speed, or maintainability. The library supplies mechanics; the project supplies visual language. Reject default component-kit styling without product rationale, but do not reject a modern lightweight library solely because a dependency was needed.
+
+Tailwind-first is valid only as an implementation fit, not as ideology or anti-ideology. Use Tailwind utilities and CSS-first tokens when they fit the chosen stack and team, but do not make pure Tailwind, vanilla CSS, shadcn/ui, or any component kit the default answer when product evidence points to stronger primitives, charts, motion, gestures, canvas, or framework tooling.
+
+For fresh projects, prefer official framework scaffolders or setup commands when current official docs show they create the supported project shape. Manual from-scratch file assembly is acceptable for tiny prototypes, educational exercises, repo-specific constraints, or when official scaffolders cannot satisfy the approved architecture; document that reason.
 ## Zero-Based Redesign Protocol
 
 When the user says "redesign from zero", "redesain dari 0", "ulang dari 0", or "research ulang":

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

@@ -10,12 +10,13 @@ When a new project is created or initialized, the agent must automatically:
 3. Review dynamic runtime signals from [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), repository evidence, task constraints, and live official documentation when runtime or ecosystem facts matter.
 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. Materialize the selected development/production assets rather than stopping at prose.
 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.
+6. Do not default fresh web projects to Next.js, Tailwind-only styling, shadcn/ui, Vite, or any framework by habit, and do not avoid them because of this guard when they are the strongest fit. Treat explicit user constraints as constraints; otherwise compare project needs, runtime boundaries, hosting, data flow, team workflow, and official setup guidance before recommending.
 
 ## Required Planning Mode
 
 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.
+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. Include at least one plausible alternative when the default-looking option is Next.js, Tailwind-only styling, shadcn/ui, or another familiar web stack.
 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.
@@ -25,12 +26,14 @@ If the user describes a project or feature, the agent must:
 If the user asks to create, complete, fix, or review project docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, or "lengkapkan docs", treat the request as documentation-first.
 
 The agent must:
-1. Materialize or refine required project docs before implementation: root `README.md` for every fresh or existing project; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` when APIs, firmware endpoints, CLI commands, or web application flows exist; `docs/database-schema.md` when persistent data exists; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
+1. Materialize or refine required project docs before implementation: root `README.md` for every fresh or existing project; `docs/doc-index.md` whenever `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` when APIs, firmware endpoints, CLI commands, or web application flows exist; `docs/database-schema.md` when persistent data exists; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
 2. Write formal project docs in English by default unless the user explicitly asks for another documentation language.
-3. Keep `README.md` public and developer friendly even for private projects: explain what the project is, who it is for, how to set it up, how to run the core workflow, how to configure it, and where deeper docs live. Do not put internal agent notes, private reasoning, secrets, or governance policy in the README.
-4. Keep documentation alive. When project behavior, setup, architecture, public contracts, data shape, deployment, or UI scope changes, update the matching docs in the same change.
-5. Avoid documentation sprawl. Add a new docs file only when the topic is stable, long enough to outgrow the README or core docs, or owned by a separate workflow such as hardware setup, deployment, troubleshooting, or testing validation.
-6. Stop after docs when the user only asked for docs. Do not write application, firmware, or UI code until the user explicitly asks for implementation or approves the implementation plan.
+3. Keep `docs/doc-index.md` short. Use it as the read-routing map with document path, purpose, reads-when triggers, status, and last-updated date. Do not duplicate the docs it points to.
+4. Keep `README.md` public and developer friendly even for private projects: explain what the project is, who it is for, how to set it up, how to run the core workflow, how to configure it, and where deeper docs live. Do not put internal agent notes, private reasoning, secrets, or governance policy in the README.
+5. Keep documentation alive. When project behavior, setup, architecture, public contracts, data shape, deployment, or UI scope changes, update the matching docs in the same change.
+6. Avoid documentation sprawl. Add a new docs file only when the topic is stable, long enough to outgrow the README or core docs, or owned by a separate workflow such as hardware setup, deployment, troubleshooting, or testing validation.
+7. Add PRD, SRS, technical-design, or separate ERD only when evidence triggers them. Use PRD for product roadmap/user-story ownership, SRS for contractual or multi-stakeholder acceptance criteria, technical-design for non-trivial architecture decisions, and a separate ERD only when `docs/database-schema.md` cannot stay readable with an embedded diagram.
+8. Stop after docs when the user only asked for docs. Do not write application, firmware, or UI code until the user explicitly asks for implementation or approves the implementation plan.
 
 ## Direct Constraint Mode
 
@@ -45,6 +48,7 @@ If the user specifies a framework, runtime, or architecture constraint, the agen
    - 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.
+   - Do not assemble a framework project from scratch by habit when official setup commands create the supported structure. Manual assembly is allowed only for tiny prototypes, educational demos, unusual repo constraints, or a documented architecture reason.
    - 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. Selected Docker lanes require files and runbooks, not docs-only acknowledgment.
 
 ## Runtime and Architecture Reference

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

@@ -11,7 +11,7 @@ Before editing:
 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 root `README.md` is missing, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
+6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/doc-index.md` is missing while `docs/` exists, if `docs/architecture-decision-record.md` is missing, or for UI scope 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.
 8. For backend/API scope, enforce layered boundaries, zero-trust input validation, safe centralized error responses, bounded list reads, transaction safety for multi-write mutations, idempotency for sensitive mutations, and behavior-focused API tests.
 9. Backend/API governance is global and stack-agnostic. Do not create stack-specific adapters or framework-specific rule branches; apply the global rules through the framework already present in the target project.

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

@@ -11,7 +11,7 @@ Before reviewing:
 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 (root `README.md`; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
+6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/doc-index.md` when `docs/` exists; `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, global domain governance must load lazily based on touched scope, and conflicting duplicate rule instructions must not appear during normal flow.
 
 Prioritize findings in this order:

package/.agent-context/review-checklists/pr-checklist.md

@@ -61,6 +61,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Scope applied: This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations
 - [ ] Style scope review is advisory and does not block merge when API docs are synced in the same commit and contract details are correct
 - [ ] Required docs exist before implementation: public and developer root README; project brief; architecture decision; flow overview; API/public contract when relevant; data model when relevant; and UI design contract when relevant.
+- [ ] `docs/doc-index.md` exists whenever `docs/` exists and acts as a compact read-routing map instead of duplicating requirements or architecture.
 - [ ] For docs-only or docs-first requests, implementation code was not changed unless the user explicitly asked for it or approved an implementation plan.
 - [ ] Formal project docs use English by default unless the user requested another language or existing docs established one.
 - [ ] Docs cover feature plan, architecture rationale, public contracts, data model, UI/design, security assumptions, testing strategy, delivery flow, and next validation actions where relevant.
@@ -73,6 +74,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Root README is public and developer friendly, even for private projects, and does not contain secrets, internal agent notes, private reasoning, or governance policy dumps.
 - [ ] Documentation grows with the project: README and matching docs were updated when setup, runtime, architecture, public contracts, data shape, deployment, validation, or UI scope changed.
 - [ ] Documentation file count stayed intentional: new docs files were added only for stable, distinct, or long workflows.
+- [ ] PRD, SRS, technical-design, or separate ERD files were added only when project evidence justified a distinct document.
 
 ## 7. UI And Accessibility
 
@@ -120,6 +122,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Security and testing requirements remain mandatory after static template purge.
 - [ ] Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing
 - [ ] Coding flow is blocked if root `README.md` is missing
+- [ ] Coding flow is blocked if `docs/doc-index.md` is missing while `docs/` exists
 - [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing
 
 ## Verdict

package/.agent-context/rules/api-docs.md

@@ -18,8 +18,12 @@ Choose README sections from project evidence. Do not force a fixed template when
 
 Documentation must evolve with the project. When behavior, setup, architecture, public contracts, data shape, deployment, or validation changes, update README and the matching docs in the same change.
 
+When `docs/` exists, keep `docs/doc-index.md` as the compact routing map for humans and agents. It should list active docs, their purpose, read triggers, status, and last update. It must not duplicate requirements, architecture, or API contracts.
+
 Start compact, then split only when a topic earns its own file. Good split signals are: the section is long, the workflow is owned separately, the content is referenced often, or the topic needs step-by-step care such as hardware setup, deployment, testing validation, operations, or troubleshooting.
 
+Use PRD, SRS, technical design, and ERD as conditional docs, not default boilerplate. PRD covers product intent and roadmap ownership. SRS covers contractual or complex acceptance criteria. Technical design covers architecture under pressure. ERD stays inside `docs/database-schema.md` unless the data model is large or relationship-heavy.
+
 ## Contract Rules
 
 - Document the public surface before or alongside implementation.

package/.agent-context/rules/architecture.md

@@ -33,6 +33,7 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Security and testing are non-negotiable baseline requirements.
 - Hard block before coding:
   - Root `README.md` must exist for every fresh or existing project and read as a public and developer entrypoint, not an internal agent note.
+  - `docs/doc-index.md` must exist whenever `docs/` exists. It is a compact read-routing map, not a replacement for project docs.
   - `docs/project-brief.md` must exist.
   - `docs/architecture-decision-record.md` (alias: `docs/Architecture-Decision-Record.md`) must exist.
   - `docs/flow-overview.md` must exist.
@@ -47,6 +48,19 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Keep docs current with project changes. Update README and the matching docs whenever setup, runtime, architecture, public contracts, data shape, UI scope, deployment, or validation flow changes.
 - Control docs file count. Keep the baseline compact, then add topic files only when a subject is stable, too long for README/core docs, or belongs to a distinct workflow such as hardware setup, deployment, testing validation, operations, or troubleshooting.
 
+## Documentation Read Routing and Conditional Specs
+
+Use `README.md` for human orientation, then use `docs/doc-index.md` to choose the smallest relevant read set. Do not broad-read every Markdown file in `docs/` by default.
+
+- Read `docs/project-brief.md`, `docs/architecture-decision-record.md`, and `docs/flow-overview.md` for broad planning, new features, or architecture changes.
+- Read `docs/api-contract.md` only when API, CLI, firmware endpoint, web flow, event, or library contract behavior is in scope.
+- Read `docs/database-schema.md` only when persistence, migrations, data shape, or query behavior is in scope.
+- Read `docs/DESIGN.md` and `docs/design-intent.json` only for UI, UX, frontend, layout, component, or visual work.
+- Add `docs/prd.md` only when there is product-roadmap, user-story, metrics, product-owner, or feature-flag ownership that would otherwise bloat the project brief.
+- Add `docs/srs.md` only for contractual, regulated, multi-stakeholder, or acceptance-criteria-heavy projects. Do not create both PRD and SRS unless those owners and purposes are distinct.
+- Add `docs/technical-design.md` only for non-trivial architecture decisions, major refactors, cross-cutting behavior, or system interactions that outgrow the ADR and flow overview.
+- Keep ERD inside `docs/database-schema.md` for small and medium schemas. Add a separate ERD file only when relationship complexity makes the schema doc hard to scan.
+
 ## Rules as Guardian (Cross-Session Consistency)
 
 - Session handoff must include active architecture contract summary.

package/.agent-context/rules/efficiency-vs-hype.md

@@ -12,6 +12,7 @@ Before adding or recommending a dependency:
 - check current official docs, release notes, and setup guidance when the ecosystem decision matters
 - choose the latest stable compatible dependency version unless a project constraint blocks it
 - use the official scaffolder or setup command when it creates the current supported project shape
+- do not hand-assemble fresh framework projects by habit when the official setup flow gives safer current defaults; document the reason when manual assembly is better
 - Only step down to an older dependency version after documenting the exact compatibility, runtime, platform, or ecosystem reason.
 - explain why the dependency is a better tradeoff than local implementation for the current task
 - avoid packages that are stale, thinly maintained, too heavy for the job, or added only because they are popular
@@ -19,3 +20,5 @@ Before adding or recommending a dependency:
 - do not reject a dependency only because it adds a package; reject it only when the project-fit, security, maintenance, compatibility, bundle/runtime, or ownership tradeoff is worse than the alternative
 
 Reject offline dependency decisions, outdated tutorial versions, trend choices, dependency avoidance choices, and performance-fear choices that are not grounded in the current repo, brief, and delivery tradeoffs.
+
+Reject framework autopilot, not frameworks. Next.js, Vite, Astro, React Router, SvelteKit, Laravel, plain HTML, and other runtimes are candidates, not defaults or forbidden choices. If the user did not constrain the stack, compare at least the strongest fit and one plausible alternative before implementation, then choose the technology that removes bottlenecks for this project.

package/.agent-context/rules/frontend-architecture.md

@@ -13,7 +13,8 @@ Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, f
 - Treat `README.md` as public and developer overview, setup, usage, and user-facing context only when design or architecture rules conflict.
 - Do not choose final style, framework, palette, typography, layout paradigm, or animation library offline.
 - Research current official docs before adding a new UI, animation, scroll, 3D, canvas, charting, icon, styling, or primitive library.
-- Dynamic UI Foundation: do not hardcode shadcn/ui, Tailwind-only, native-only, or any component library as the universal answer. Modern lightweight primitives, motion libraries, canvas/WebGL helpers, charting libraries, and styling tools are valid when product evidence, accessibility, interaction quality, maintainability, delivery speed, runtime constraints, and official docs support them.
+- Dynamic UI Foundation: do not hardcode shadcn/ui, Tailwind-only, native-only, or any component library as the universal answer, and do not avoid them out of guardrail fear when they fit. Tailwind-first is valid when the stack, token model, and team workflow support it; pure Tailwind, vanilla CSS, shadcn/ui, or any kit is not neutral by itself. Modern primitives, motion/canvas/WebGL helpers, charting libraries, and styling tools are valid when product evidence, accessibility, runtime constraints, and official docs support them.
+- For fresh projects, prefer official framework scaffolders or setup commands when official docs show they produce the current supported shape. Build files manually only when approved architecture, repo constraints, or learning/prototype scope makes that better.
 - Keep design continuity opt-in. Repo evidence outranks memory residue.
 
 ## Required Design Contract
@@ -54,6 +55,7 @@ If the user gives no current-task visual research or reference:
 - Do not count old UI, existing design docs, or scaffold seeds as research.
 - Choose one high-variance non-software conceptual anchor before UI code.
 - Internally reject the safest dashboard, portal, card-grid, admin-shell, or minimalist-web-app mental model.
+- Do not let the fallback anchor become a generic place metaphor. Avoid room, darkroom, counting room, control room, war room, studio, lab, cockpit, and command center unless the product actually depends on that place model; prefer product-specific artifacts, workflows, custody chains, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms over "where the UI lives".
 - Record one real-world anchor reference, one signature motion behavior, and one typographic decision with role contrast.
 - Derive typography, spacing, morphology, motion, and responsive recomposition from that anchor.
 - Translate the anchor into workflow, hierarchy, density, typography, state behavior, and interaction before using literal artifacts. Do not turn anchor artifacts into required chrome, wallpaper, decorative props, or component-kit theme objects without a named product function.
@@ -71,7 +73,7 @@ If the user gives no current-task visual research or reference:
 - For new screens or broad redesigns, research the expressive implementation path instead of defaulting to static native CSS. Use native or already-installed tools only when they can still deliver the chosen ambition, or when a concrete blocker is documented. Do not downshift because adding a package feels inconvenient; downshift only for a concrete product-fit, accessibility, security, compatibility, device, maintenance, or measured performance reason.
 - Keep reduced-motion, keyboard, loading, performance, mobile, and non-3D fallbacks explicit.
 - Use component kits or headless primitives for behavior and accessibility when they fit. Replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.
-- Keep design-intent flexible: lock user goals, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component skins, and candidate signature moves flexible until evidence or approval locks them.
+- Keep design-intent flexible: lock user goals, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component skins, candidate signature moves, and external website inspiration flexible until evidence or approval locks them. Convert references into product-fit rules; do not copy layout, palette, component skin, brand posture, or visual metaphor.
 ## Zero-Based Redesign
 
 If the user asks for a redesign from zero:

package/.cursor/rules/agentic-senior-core.mdc

@@ -7,7 +7,7 @@ alwaysApply: true
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.

package/.cursorrules

@@ -1,6 +1,6 @@
 # .cursorrules - Legacy Thin Adapter
 
-Generated by Agentic-Senior-Core CLI v3.0.45
+Generated by Agentic-Senior-Core CLI v3.0.47
 Adapter Mode: legacy-thin
 Adapter Source: .agent-instructions.md when present; fallback .instructions.md
 Canonical baseline: .instructions.md

package/.gemini/instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../.instructions.md) as the canonical policy source.

package/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../.instructions.md) as the canonical policy source.

package/.github/instructions/agentic-senior-core.instructions.md

@@ -6,7 +6,7 @@ applyTo: "**"
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.

package/.instructions.md

@@ -44,7 +44,7 @@ Load only relevant rule files. Do not read the entire rule directory by default.
 
 Available rules: `naming-conv.md`, `architecture.md`, `security.md`, `performance.md`, `error-handling.md`, `testing.md`, `git-workflow.md`, `efficiency-vs-hype.md`, `api-docs.md`, `microservices.md`, `event-driven.md`, `database-design.md`, `realtime.md`, `frontend-architecture.md`, `docker-runtime.md`.
 
-For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. For framework or package setup work, use the latest stable compatible dependency set and official setup flow unless a documented compatibility constraint blocks it. New dependencies are allowed when they improve efficiency, delivery time, correctness, accessibility, UX, or maintainability. Do not treat dependency avoidance or vague performance fear as a default reason to skip a modern maintained library.
+For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. For framework or package setup work, use the latest stable compatible dependency set and official setup flow unless a documented compatibility constraint blocks it. Prefer official framework scaffolders when they create the supported project shape; manual file assembly needs a repo, prototype, learning, or architecture reason. New dependencies are allowed when they improve efficiency, delivery time, correctness, accessibility, UX, or maintainability. Do not treat dependency avoidance or vague performance fear as a default reason to skip a modern maintained library.
 
 Backend/API routing:
 - Data/schema/persistence: `architecture.md`, `database-design.md`, `performance.md`, `testing.md`.
@@ -59,13 +59,13 @@ Use the union once when scopes overlap. Do not create framework-specific governa
 
 Runtime Decision Signals come from project context, repo evidence, and live research. Runtime signals are evidence gates, not style cues or popularity rankings.
 
-For fresh projects, recommend runtime/framework from the brief, constraints, and live official docs before coding. For existing projects, treat detected markers as evidence only. Ignore pattern frequency, external rankings, and remembered defaults.
+For fresh projects, recommend runtime/framework from the brief, constraints, and live official docs before coding. For existing projects, treat detected markers as evidence only. Ignore pattern frequency, external rankings, and remembered defaults. Do not default web projects to Next.js, Tailwind-only styling, shadcn/ui, Vite, or any familiar web stack by habit, and do not avoid them because of this guard when they are the strongest project fit.
 
 ### Layer 3: Structural Planning Signals
 
 Structural Planning Signals use dynamic structural planning from repo context, docs, runtime constraints, and live research. Structural planning signals are not a hard whitelist.
 
-For new projects or modules, extract constraints, boundaries, and required docs first. Do not silently choose frameworks or architecture from offline heuristics. If runtime or architecture is unresolved, produce a short recommendation from evidence and live official documentation before coding.
+For new projects or modules, extract constraints, boundaries, and required docs first. Do not silently choose frameworks or architecture from offline heuristics. If runtime or architecture is unresolved, produce a short recommendation from evidence and live official documentation before coding. Compare at least one plausible alternative when the strongest-looking option is a familiar web default and the user did not explicitly choose it.
 
 ### Layer 4: Execution Contracts
 
@@ -97,7 +97,7 @@ Use `.agent-context/policies/` for quality gates, release thresholds, and audit
 
 ### Layer 9: Project Context
 
-Use root `README.md` as the public and developer entrypoint for every fresh or existing project. Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`, `database-schema.md`, `api-contract.md`, `flow-overview.md`, `DESIGN.md`, `design-intent.json`.
+Use root `README.md` as the public and developer entrypoint for every fresh or existing project. Use `docs/doc-index.md` as the compact routing map when `docs/` exists. Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`, `database-schema.md`, `api-contract.md`, `flow-overview.md`, `DESIGN.md`, `design-intent.json`.
 
 ## Mandatory Triggers
 
@@ -106,9 +106,10 @@ Use root `README.md` as the public and developer entrypoint for every fresh or e
 Trigger: docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, or "lengkapkan docs".
 
 1. Load `architecture.md`, `api-docs.md`, and only additional rules required by scope.
-2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` for APIs, firmware endpoints, CLI commands, or web application flows; `docs/database-schema.md` for persistent data; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
-3. Write formal project docs in English by default unless the user asks otherwise.
-4. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation.
+2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/doc-index.md` whenever `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` for APIs, firmware endpoints, CLI commands, or web application flows; `docs/database-schema.md` for persistent data; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
+3. Use `docs/doc-index.md` as the compact read-routing map. Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.
+4. Write formal project docs in English by default unless the user asks otherwise.
+5. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation.
 
 ### 2. New Project Planning
 
@@ -148,6 +149,8 @@ Trigger: ui, ux, layout, screen, tailwind, frontend, redesign.
 6. Generate or refine `docs/DESIGN.md` plus `docs/design-intent.json` before UI implementation.
 7. Keep context isolated; do not eagerly load unrelated backend-only rules.
 8. In UI Design Mode, choose the ambition level proactively. For broad screens or redesigns, treat expressive motion, spatial hierarchy, distinctive composition, and product-specific interaction as the baseline even when the user did not say "rich"; quiet or static surfaces require a concrete product, performance, accessibility, device, or dependency reason.
+9. Do not let conceptual anchors collapse into room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center by habit. Prefer artifacts, workflows, custody chains, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms unless a physical place model is core to the product.
+10. External websites and benchmark examples are candidate evidence for constraints, mechanics, and quality bars only. Do not copy their layout rhythm, palette, component skin, visual metaphor, or brand posture without explicit user approval and product-fit rationale.
 
 ## Reasoning Chain
 

package/.windsurf/rules/agentic-senior-core.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](../../.instructions.md) as the canonical policy source.

package/.windsurfrules

@@ -1,6 +1,6 @@
 # .windsurfrules - Legacy Thin Adapter
 
-Generated by Agentic-Senior-Core CLI v3.0.45
+Generated by Agentic-Senior-Core CLI v3.0.47
 Adapter Mode: legacy-thin
 Adapter Source: .agent-instructions.md when present; fallback .instructions.md
 Canonical baseline: .instructions.md

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.

package/GEMINI.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
+Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
 
 This repository is governed by a strict instruction contract.
 Use [.instructions.md](.instructions.md) as the canonical policy source.

package/README.md

@@ -34,6 +34,8 @@ One command to initialize rules, checklists, thin discovery adapters, and a comp
 > **See [docs/deep-dive.md](docs/deep-dive.md) and [docs/roadmap.md](docs/roadmap.md) for advanced configuration, planning mode, snapshot, and realtime options.**
 
 - This command writes `.agent-context/state/v3-purge-audit.json` and reports whether static directory deletion is safe.
+- When project docs are scaffolded, `docs/doc-index.md` is used as the compact map for deeper docs so agents can read the right files without scanning every Markdown file.
+- Local backup snapshots are written under `.agentic-backup/`; init and upgrade ensure that folder is ignored by the target repository.
 - Package scope is `@ryuenn3123`; the GitHub repository owner is `fatidaprilian`.
 
 ---
@@ -95,6 +97,8 @@ Use `--dry-run` first to preview changes safely, then apply with `--yes`.
 Upgrade now performs managed-surface synchronization by default: obsolete governance files under managed paths are pruned so the pack stays aligned with the latest release.
 Use `--no-prune` if you want to keep legacy managed files.
 
+When upgrade creates `.agentic-backup/`, it also keeps the target root `.gitignore` aligned with that local-only backup folder. The backup is for rollback safety, not a source of truth and not a file to commit.
+
 ## Instruction Entrypoints
 
 The canonical source is `.instructions.md`.

package/lib/cli/backup.mjs

@@ -4,6 +4,9 @@ import crypto from 'node:crypto';
 import { pathExists, ensureDirectory } from './utils.mjs';
 import { entryPointFiles, BACKUP_DIR_NAME } from './constants.mjs';
 
+const BACKUP_GITIGNORE_ENTRY = `${BACKUP_DIR_NAME}/`;
+const BACKUP_GITIGNORE_COMMENT = '# agentic-senior-core: local backup artifacts';
+
 /**
  * Calculates a SHA-256 hash of a file's contents.
  */
@@ -54,6 +57,7 @@ export async function createBackup(targetDirectoryPath) {
   await ensureDirectory(objectsDir);
 
   const pathsToTrack = [
+    path.join(targetDirectoryPath, '.gitignore'),
     ...entryPointFiles.map((entryPointFileName) => path.join(targetDirectoryPath, entryPointFileName)),
     path.join(targetDirectoryPath, '.agent-context'),
   ];
@@ -122,3 +126,36 @@ export async function createBackup(targetDirectoryPath) {
     durationMs: Date.now() - startTime
   };
 }
+
+export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
+  const gitignorePath = path.join(targetDirectoryPath, '.gitignore');
+  const existingContent = await pathExists(gitignorePath)
+    ? await fs.readFile(gitignorePath, 'utf8')
+    : '';
+  const existingLines = existingContent.split(/\r?\n/).map((line) => line.trim());
+
+  if (existingLines.includes(BACKUP_GITIGNORE_ENTRY) || existingLines.includes(BACKUP_DIR_NAME)) {
+    return {
+      status: 'unchanged',
+      gitignorePath,
+      entry: BACKUP_GITIGNORE_ENTRY,
+    };
+  }
+
+  let nextContent = existingContent;
+  if (nextContent.length > 0 && !nextContent.endsWith('\n')) {
+    nextContent += '\n';
+  }
+  if (nextContent.length > 0 && !nextContent.endsWith('\n\n')) {
+    nextContent += '\n';
+  }
+  nextContent += `${BACKUP_GITIGNORE_COMMENT}\n${BACKUP_GITIGNORE_ENTRY}\n`;
+
+  await fs.writeFile(gitignorePath, nextContent, 'utf8');
+
+  return {
+    status: existingContent ? 'updated' : 'created',
+    gitignorePath,
+    entry: BACKUP_GITIGNORE_ENTRY,
+  };
+}

package/lib/cli/commands/init.mjs

@@ -44,7 +44,7 @@ import {
   resolveDetectedSetupDecision,
 } from '../init-detection-flow.mjs';
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup } from '../backup.mjs';
+import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
 import {
   runProjectDiscovery,
   generateProjectDocumentation,
@@ -376,6 +376,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     detectionTransparency.decision.selectedProjectScopeLabel = selectedProjectScopeLabel;
 
     await createBackup(resolvedTargetDirectoryPath);
+    const backupGitignoreResult = await ensureBackupGitignoreEntry(resolvedTargetDirectoryPath);
+    if (backupGitignoreResult.status !== 'unchanged') {
+      console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
+    }
 
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
       includeMcpTemplate: shouldIncludeMcpTemplate,

package/lib/cli/commands/upgrade.mjs

@@ -41,7 +41,7 @@ import {
 } from '../compiler.mjs';
 
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup } from '../backup.mjs';
+import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
 import { performRollback } from '../rollback.mjs';
 import {
   detectProjectDocTemplateStaleness,
@@ -399,6 +399,10 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     }
 
     await createBackup(resolvedTargetDirectoryPath);
+    const backupGitignoreResult = await ensureBackupGitignoreEntry(resolvedTargetDirectoryPath);
+    if (backupGitignoreResult.status !== 'unchanged') {
+      console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
+    }
 
     try {
       const governanceSyncResult = await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {

package/lib/cli/compiler.mjs

@@ -422,8 +422,10 @@ export async function buildCompiledRulesContent({
       '3. .agent-context/prompts/review-code.md -> review, audit, check, analyze',
       '4. .agent-context/prompts/bootstrap-design.md -> ui, ux, layout, screen, tailwind, frontend, redesign',
       'Documentation-first policy:',
-      '- Create or refine required project docs before implementation: README.md for every fresh or existing project; docs/project-brief.md; docs/architecture-decision-record.md; docs/flow-overview.md; docs/api-contract.md when APIs, firmware endpoints, CLI commands, or web application flows exist; docs/database-schema.md when persistent data exists; and docs/DESIGN.md plus docs/design-intent.json for UI scope.',
+      '- Create or refine required project docs before implementation: README.md for every fresh or existing project; docs/doc-index.md whenever docs/ exists; docs/project-brief.md; docs/architecture-decision-record.md; docs/flow-overview.md; docs/api-contract.md when APIs, firmware endpoints, CLI commands, or web application flows exist; docs/database-schema.md when persistent data exists; and docs/DESIGN.md plus docs/design-intent.json for UI scope.',
       '- Keep README.md public and developer friendly, including for private projects: explain what the project is, who it is for, setup, usage, configuration, and links to deeper docs. Do not put secrets, internal agent notes, private reasoning, or governance policy dumps in it.',
+      '- Use docs/doc-index.md as the compact read-routing map before selecting deeper docs. Do not broad-read docs/*.md by default.',
+      '- Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.',
       '- Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
       '- Write formal project docs in English by default unless the user explicitly asks for another documentation language.',
       '- For docs-only/docs-first requests, do not write application, firmware, or UI code until the user asks or approves an implementation plan.',
@@ -546,14 +548,22 @@ export async function buildCompiledRulesContent({
 
   if (await pathExists(projectBriefPath)) {
     const hasRootReadme = await pathExists(path.join(resolvedTargetDirectoryPath, 'README.md'));
-    const projectDocsEntries = ['project-brief.md'];
+    const projectDocsEntries = [];
     const candidateDocFileNames = [
+      'doc-index.md',
+      'project-brief.md',
       'architecture-decision-record.md',
+      'technical-design.md',
+      'prd.md',
+      'srs.md',
       'database-schema.md',
+      'erd.md',
       'api-contract.md',
       'flow-overview.md',
       'DESIGN.md',
       'design-intent.json',
+      'runbook.md',
+      'troubleshooting.md',
     ];
 
     for (const candidateFileName of candidateDocFileNames) {
@@ -573,6 +583,7 @@ export async function buildCompiledRulesContent({
         '',
         'Universal SOP hard block policy:',
         '- README.md must exist and read as a public and developer entrypoint.',
+        '- docs/doc-index.md must exist whenever docs/ exists and act as the compact read-routing map.',
         '- Stop implementation if docs/project-brief.md is missing.',
         '- Stop implementation if docs/architecture-decision-record.md (alias: docs/Architecture-Decision-Record.md) is missing.',
         '- Stop implementation if docs/flow-overview.md is missing.',
@@ -580,6 +591,8 @@ export async function buildCompiledRulesContent({
         '- If the product exposes API or web application flows, docs/api-contract.md must exist before coding continues.',
         '- For UI scope, stop implementation if docs/DESIGN.md or docs/design-intent.json is missing.',
         '- Keep README.md overview-level, public, and developer friendly; do not put secrets, internal agent notes, private reasoning, or governance policy dumps in it.',
+        '- Use README.md plus docs/doc-index.md to choose the smallest relevant read set before loading deeper docs.',
+        '- Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.',
         '- Materialize missing docs first, then continue coding.',
         '- Bootstrap missing docs from real repo evidence and the latest user request. Do not write generic placeholder templates.',
         '- Separate confirmed facts from assumptions and end each major explanation with the next validation action.',
@@ -612,10 +625,12 @@ export async function buildCompiledRulesContent({
         '',
         'Bootstrap policy:',
         '- Create README.md as a public and developer entrypoint before coding continues.',
+        '- Create docs/doc-index.md as the compact read-routing map whenever docs/ exists.',
         '- Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
         '- docs/flow-overview.md must also exist before coding continues.',
         '- Add docs/database-schema.md when persistent data is involved.',
         '- Add docs/api-contract.md when API or web application flows are involved.',
+        '- Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.',
         '- For docs-only/docs-first requests, stop after docs unless the user asks for implementation or approves an implementation plan.',
         '- If docs/project-brief.md is missing, execute bootstrap-project-context prompt immediately.',
         hasBootstrapDesignPrompt

package/lib/cli/project-scaffolder/constants.mjs

@@ -6,6 +6,7 @@ export const PROJECT_DOC_FILE_NAMES = [
   'api-contract.md',
   'flow-overview.md',
 ];
+export const DOC_INDEX_FILE_NAME = 'doc-index.md';
 export const UI_DESIGN_CONTRACT_FILE_NAMES = ['DESIGN.md', 'design-intent.json'];
 
 // Legacy project docs may still carry this version header; keep for upgrade staleness checks.

package/lib/cli/project-scaffolder/design-contract/validation.mjs

@@ -236,7 +236,8 @@ export function validateDesignIntentContract(designIntentContract) {
       !Array.isArray(conceptualAnchor.sourceDomains)
       || conceptualAnchor.sourceDomains.length < 4
       || !conceptualAnchor.sourceDomains.includes('complex-physical-engineering')
-      || !conceptualAnchor.sourceDomains.includes('cinematic-spatial-interface')
+      || !conceptualAnchor.sourceDomains.includes('cinematic-behavior-and-transition-systems')
+      || !conceptualAnchor.sourceDomains.includes('workflow-and-custody-systems')
       || !conceptualAnchor.sourceDomains.includes('premium-interactive-web-experiences')
     ) {
       validationErrors.push('designIntent.conceptualAnchor.sourceDomains must list broad non-template anchor domains.');

package/lib/cli/project-scaffolder/design-contract.mjs

@@ -29,6 +29,12 @@ const GENERICITY_DRIFT_SIGNALS = [
   'literal-anchor-artifacts-used-as-required-ui-chrome',
   'candidate-signature-move-treated-as-locked-implementation',
   'library-theme-tokens-drive-visual-language',
+  'spatial-room-anchor-used-by-habit',
+  'place-metaphor-used-as-layout-model-without-product-function',
+  'external-website-reference-copied-as-style',
+  'tailwind-only-or-component-kit-used-as-neutrality-claim',
+  'framework-selected-by-familiarity-instead-of-evidence',
+  'manual-framework-scaffold-used-when-official-setup-fits',
 ];
 
 const FORBIDDEN_PATTERN_SIGNALS = [
@@ -50,6 +56,9 @@ const VALID_BOLD_SIGNALS = [
   'headless-or-component-primitive-restyled-to-product-language',
   'responsive-recomposition-by-task-priority',
   'purposeful-motion-with-reduced-motion-path',
+  'non-spatial-product-anchor-or-workflow-mechanism',
+  'official-scaffolder-used-for-supported-project-shape',
+  'framework-choice-compared-against-plausible-alternative',
 ];
 
 export function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
@@ -202,11 +211,14 @@ function buildDesignIntentContractObject({
         'component-kit-theme-mapping',
         'signature-move-implementation',
         'literal-anchor-artifacts',
+        'spatial-metaphor-and-place-language',
       ],
       tokenLockingRule: 'Semantic roles are required, but exact primitive values stay flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them.',
       signatureMovePolicy: 'Record the required experience outcome separately from candidate implementation moves; replace a candidate move when another move better fits the product.',
       libraryVisualLanguagePolicy: 'Libraries supply behavior, accessibility, primitives, and delivery speed; they must not dictate final composition, theme, morphology, or visual language.',
       literalAnchorPolicy: 'Translate anchors into workflow, hierarchy, density, typography, material behavior, state language, and interaction grammar before requiring literal props, marks, or chrome.',
+      spatialMetaphorPolicy: 'Do not default anchors to room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center. Use place metaphors only when the product truly depends on a physical place model.',
+      externalInspirationPolicy: 'External websites and examples are candidate evidence for constraints, mechanics, and quality bars; do not copy their layout rhythm, palette, component skin, brand posture, or visual metaphor.',
     },
     conceptualAnchor: {
       mode: 'required-when-no-external-research',
@@ -227,6 +239,8 @@ function buildDesignIntentContractObject({
         preferDistinctiveOverSafe: true,
         doNotRevealHiddenCandidateList: true,
         outputOnlyChosenAnchor: true,
+        avoidSpatialPlaceMetaphorByDefault: true,
+        preferMechanismOverPlace: true,
       },
       creativeCommitmentPolicy: {
         requiredBeforeComplianceReview: true,
@@ -246,12 +260,23 @@ function buildDesignIntentContractObject({
         'saas-shell',
         'minimalist-interface',
         'safe-admin-layout',
+        'room',
+        'darkroom',
+        'counting-room',
+        'control-room',
+        'war-room',
+        'studio',
+        'lab',
+        'cockpit',
+        'command-center',
       ],
       sourceDomains: [
         'complex-physical-engineering',
-        'cinematic-spatial-interface',
+        'cinematic-behavior-and-transition-systems',
         'experimental-editorial-structure',
         'scientific-instrumentation',
+        'workflow-and-custody-systems',
+        'material-artifacts-and-instruments',
         'premium-interactive-web-experiences',
       ],
       visualRiskBudget: {
@@ -266,6 +291,12 @@ function buildDesignIntentContractObject({
         allowedLiteralUse: 'Only use literal anchor artifacts when they serve a named product function, control, state, or task overlay.',
         forbiddenLiteralUse: 'Do not turn anchor artifacts into decorative wallpaper, required chrome, default texture, or unavoidable theme props.',
       },
+      spatialAutopilotPolicy: {
+        forbiddenHabitTerms: ['room', 'darkroom', 'counting-room', 'control-room', 'war-room', 'studio', 'lab', 'cockpit', 'command-center'],
+        allowedOnlyWhen: 'The product has a real physical place model, operational environment, or user workflow that depends on that place metaphor.',
+        replacementPreference: 'Use artifacts, custody flows, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms.',
+        reviewQuestion: 'Could this anchor still work if the word "room" was removed? If not, revise before UI code.',
+      },
       requiredDerivedAxes: [
         'typography',
         'morphology',
@@ -370,7 +401,9 @@ function buildDesignIntentContractObject({
         sourceUrl: null,
         stableVersion: null,
         fallbackIfUnavailable: 'Use native CSS, browser APIs, or existing dependencies.',
-        selectionPolicy: 'Do not default to shadcn, native-only, Tailwind-only, or dependency avoidance by habit.',
+        selectionPolicy: 'Do not default to shadcn, native-only, Tailwind-only, or dependency avoidance by habit; do not avoid them out of guardrail fear when they fit.',
+        officialScaffolderPolicy: 'For fresh projects, prefer official setup commands when they create the supported project shape; manual assembly requires a documented repo, learning, prototype, or architecture reason.',
+        frameworkNeutralityPolicy: 'Next.js, Vite, Astro, React Router, SvelteKit, Laravel, and plain HTML are candidates, not defaults or forbidden choices. Compare at least one plausible alternative when no framework is user-constrained, then choose the technology that removes bottlenecks for this project.',
       },
     ],
     mathSystems: {
@@ -687,9 +720,12 @@ function buildDesignIntentContractObject({
       requireExplicitContinuityApproval: true,
       forbidCarryoverWhenUnapproved: true,
       approvedExternalConstraintUsage: 'Convert approved external constraints into current-project rules; do not imitate source surfaces.',
+      externalWebsiteReferencePolicy: 'Use outside websites for mechanics, constraints, and quality bar analysis only. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
       driftSignals: [
         'palette-reused-without-brief-support',
         'prior-ui-visual-dna-carried-into-reset-request',
+        'room-or-control-room-anchor-repeated-without-product-need',
+        'external-reference-copied-instead-of-translated',
       ],
     },
     forbiddenPatterns: [...FORBIDDEN_PATTERN_SIGNALS],

package/lib/cli/project-scaffolder/discovery.mjs

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import { askChoice, askYesNo } from '../utils.mjs';
 import {
   ARCHITECTURE_STYLE_CHOICES,
+  DOC_INDEX_FILE_NAME,
   DOCKER_STRATEGY_CHOICES,
   SUPPORTED_DOC_LANGUAGES,
 } from './constants.mjs';
@@ -169,6 +170,7 @@ export function resolveProjectDocTargets(discoveryAnswers) {
     || discoveryAnswers.primaryDomain.toLowerCase().includes('fullstack');
 
   const requiredDocFileNames = [
+    DOC_INDEX_FILE_NAME,
     'project-brief.md',
     'architecture-decision-record.md',
     'flow-overview.md',

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -78,7 +78,9 @@ export function buildProjectContextBootstrapPrompt({
     '12. Treat topology as an agent decision unless the user explicitly constrained it. If monolith fits, explain why. If a service split fits, document the evidence and service boundary logic.',
     '13. Required docs coverage must include a public and developer README entrypoint, feature plan, architecture rationale, flow, public API or integration contracts when relevant, data model when relevant, UI/design when relevant, security assumptions, testing strategy, runtime/deployment notes, and next validation actions.',
     '14. README.md must be public and developer friendly, including for private projects: what it is, who it is for, setup, core workflow, configuration, and links to deeper docs. Do not include secrets, internal agent notes, private reasoning, or governance policy dumps.',
-    '15. Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
+    '15. docs/doc-index.md is the low-token routing map for docs/*. Keep it short, list each active doc, and explain when an agent should read it. Do not make it the source of truth for requirements or architecture.',
+    '16. Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
+    '17. Add SRS, PRD, technical-design, or ERD docs only when project evidence triggers them. Use PRD for product-roadmap/user-story ownership, SRS for contractual or multi-stakeholder acceptance criteria, technical-design for non-trivial architecture decisions, and ERD only as a separate file when the schema is too complex for docs/database-schema.md.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -105,10 +107,12 @@ export function buildProjectContextBootstrapPrompt({
     '## Required Execution',
     '1. Create all required docs files listed above with complete Markdown content.',
     '2. Make the docs adaptive to the real repo and prompt context. These are living references, not frozen templates.',
-    '3. In docs/project-brief.md and docs/architecture-decision-record.md, include explicit sections for confirmed facts, assumptions to validate, and next validation actions whenever context is incomplete.',
-    '4. Before implementation, use the docs to confirm stack, runtime, architecture, public contracts, data, validation, and delivery assumptions.',
-    '5. Keep content original, specific to this project, and actionable for implementation.',
-    '6. After writing docs, continue coding tasks using these docs as living project context.',
+    '3. In docs/doc-index.md, include a compact table with document path, purpose, reads-when triggers, status, and last-updated date.',
+    '4. In docs/project-brief.md and docs/architecture-decision-record.md, include explicit sections for confirmed facts, assumptions to validate, and next validation actions whenever context is incomplete.',
+    '5. Before implementation, use README.md plus docs/doc-index.md to select only the relevant docs for the current task instead of broad-reading docs/*.md.',
+    '6. Before implementation, use the docs to confirm stack, runtime, architecture, public contracts, data, validation, and delivery assumptions.',
+    '7. Keep content original, specific to this project, and actionable for implementation.',
+    '8. After writing docs, continue coding tasks using these docs as living project context.',
     '',
   ].join('\n');
 }
@@ -214,13 +218,17 @@ export function buildDesignBootstrapPrompt({
     '25. In Dynamic Avant-Garde mode, consider three high-variance anchors, discard the two safest or most predictable options, and output only the chosen anchor.',
     '26. Reject final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.',
     '27. Reject anchors described only as modern, clean, premium, expressive, minimal, or bold.',
+    '27a. Do not default anchors to room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center unless the product genuinely depends on that physical place model.',
+    '27b. Prefer artifacts, custody flows, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms over "where the interface lives".',
     '28. Set conceptualAnchor.anchorReference and make derivedTokenLogic.anchorReference match exactly.',
     '29. Fill derivedTokenLogic before code. If a token cannot trace to anchorReference, revise it.',
     '29a. Lock semantic roles before exact values. Do not freeze fonts, color primitives, radius, shadows, or component-kit theme treatment unless repo evidence, accessibility validation, implementation constraints, or explicit user approval requires it.',
     '30. Research current official docs before importing any new UI-related library.',
-    '31. Do not default to shadcn/ui, Tailwind-only, native-only, or any component kit by habit; choose the UI foundation from product fit, accessibility, interaction quality, runtime constraints, and official docs.',
+    '31. Do not default to shadcn/ui, Tailwind-only, native-only, or any component kit by habit, and do not avoid them out of guardrail fear; choose the UI foundation from product fit, accessibility, interaction quality, runtime constraints, and official docs.',
     '32. If research is unavailable, set libraryResearchStatus to pending-verification and use native CSS, browser APIs, or existing dependencies only when they can preserve the intended ambition.',
     '33. Do not reject modern lightweight libraries solely because they add a dependency; package count or vague performance fear is not a blocker by itself.',
+    '33a. Tailwind-first is valid only when the stack, token model, and team workflow support it; pure Tailwind, vanilla CSS, shadcn/ui, or any component kit is not neutral by default and not forbidden by default.',
+    '33b. For fresh framework projects, prefer official setup commands when official docs show they create the supported project shape; manual file assembly requires a repo, prototype, learning, or architecture reason.',
     '34. Define reviewRubric and require genericity findings to name the actual drift signal.',
     '35. Separate taste from failure. Bold accessible work is valid.',
     '36. For zero-based redesign, create visualResetStrategy and reset composition, hierarchy, palette/typography, motion or interaction, and responsive information architecture.',
@@ -228,6 +236,7 @@ export function buildDesignBootstrapPrompt({
     '38. Do not make core user workflows terminal-only unless the product is explicitly a CLI, developer tool, or operational runbook.',
     '39. Separate required experience outcomes from candidate implementation moves. Candidate signature moves are proposals until product evidence, accessibility, or user approval makes them required.',
     '40. Translate conceptual anchors non-literally first. Do not turn anchor artifacts into required chrome, decorative props, wallpaper, or theme objects unless they serve a named product function.',
+    '41. Use external websites and benchmark examples as candidate evidence for constraints, mechanics, and quality bars only; do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
     '',
     '## Creative Ambition Floor',
     'Before implementation, the design contract must name one authored visual bet, one product-derived palette move, one signature motion/spatial/interaction behavior, and one morphology or composition choice that would not appear in a generic AI template.',
@@ -244,6 +253,7 @@ export function buildDesignBootstrapPrompt({
     'If web search is available, verify every new UI, animation, scroll, 3D, canvas, chart, icon, styling, or primitive library against current official docs and record source URL, fetched date, stable compatible version, purpose, risk, and fallback.',
     'If web search is unavailable or fails, set libraryResearchStatus to pending-verification, record LIBRARY_TO_VERIFY notes, and use native CSS, browser APIs, or already-present project dependencies only when they can preserve the intended ambition until verification is possible.',
     'Select UI foundations dynamically. Use ready-made primitives or component kits for mechanics when they fit, but replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.',
+    'For fresh projects, compare the user-constrained or strongest-fit framework against at least one plausible alternative when no framework is explicitly selected. Do not let Next.js or any familiar web stack win by pattern frequency.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.45",
+  "version": "3.0.47",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/validate/config.mjs

@@ -196,6 +196,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       '### 1. Documentation-First Mode',
       'root `README.md` for every fresh or existing project',
+      'docs/doc-index.md',
       'Stop after documentation when the user only asked for docs.',
       'Do not write application, firmware, or UI code',
     ],
@@ -205,6 +206,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       '## Universal SOP Baseline (Mandatory)',
       'Root `README.md` must exist for every fresh or existing project',
+      '`docs/doc-index.md` must exist whenever `docs/` exists',
       'Security and testing are non-negotiable baseline requirements.',
       'If required project context docs are missing, stop implementation and bootstrap docs before writing application code.',
     ],
@@ -214,6 +216,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       '## Documentation-First Requests',
       'root `README.md` for every fresh or existing project',
+      '`docs/doc-index.md` whenever `docs/` exists',
       'Stop after docs when the user only asked for docs.',
       'Write formal project docs in English by default',
     ],
@@ -230,19 +233,20 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
   {
     path: '.agent-context/prompts/review-code.md',
     snippets: [
-      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).',
+      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).',
     ],
   },
   {
     path: '.agent-context/prompts/refactor.md',
     snippets: [
-      '6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.',
+      '6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/doc-index.md` is missing while `docs/` exists, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.',
     ],
   },
   {
     path: 'lib/cli/compiler.mjs',
     snippets: [
       'Universal SOP hard block policy:',
+      'docs/doc-index.md whenever docs/ exists',
       'README.md must exist and read as a public and developer entrypoint',
       'Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
       'Documentation-first policy:',