@ryuenn3123/agentic-senior-core 3.0.46 → 3.0.48

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

@@ -26,19 +26,21 @@ 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
 
 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.
+3. Reference [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [AGENTS.md](../../AGENTS.md), and the relevant `.agent-context/` files 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.
@@ -51,7 +53,7 @@ If the user specifies a framework, runtime, or architecture constraint, the agen
 
 ## 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.
+See [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [AGENTS.md](../../AGENTS.md), and the relevant `.agent-context/` files for the latest shipped runtime evidence, explicit constraints, and agent-decision status.
 
 ## UI/UX Bootstrap
 

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.
@@ -64,8 +78,8 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 
 ## Single Source of Truth and Lazy Rule Loading
 
-- Canonical rule source is .instructions.md.
-- Adapter entry files stay thin and must point to the canonical source.
+- Canonical rule source is AGENTS.md.
+- Native adapter entry files stay thin and must import the canonical source.
 - Load global domain rules lazily based on touched scope.
 - Do not create or load stack-specific governance adapters as the baseline.
 - Runtime or framework evidence can clarify implementation details, but it must not replace the global architecture, security, data, API, error, event, and testing boundaries.

package/.agent-context/state/architecture-map.md

@@ -6,10 +6,10 @@ Use this file as repo-local agent context. It records the current governance arc
 
 | Surface | Criticality | Change Policy | Required Checks |
 | --- | --- | --- | --- |
-| `.instructions.md`, `AGENTS.md`, generated adapters | critical | Keep `.instructions.md` canonical and adapters thin/hash-synced | `npm run sync:adapters`, `npm run check:adapters`, `npm run validate` |
+| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` | critical | Keep `AGENTS.md` canonical and native bridges minimal | `npm run sync:adapters`, `npm run check:adapters`, `npm run validate` |
 | `.agent-context/rules/**`, `.agent-context/prompts/**`, `.agent-context/review-checklists/**` | critical | Keep rules imperative, compact, scope-resolved, and non-duplicative | adapter sync, validation, targeted smoke tests |
 | `.agent-context/state/**` | high | Track only seed/config and current operational state; keep generated reports local-only | `npm pack --dry-run`, state README review |
-| `lib/cli/compiler.mjs`, `scripts/sync-thin-adapters.mjs` | critical | Preserve generated surface compatibility across Codex, Cursor, Windsurf, Copilot, Claude, and Gemini | adapter tests, smoke tests, validation |
+| `scripts/sync-thin-adapters.mjs` | critical | Preserve minimal import bridge compatibility for Claude and Gemini | adapter tests, smoke tests, validation |
 | `lib/cli/commands/init.mjs`, `lib/cli/commands/upgrade.mjs` | high | Preserve fresh-project and existing-project behavior without silent stack/style decisions | CLI smoke tests, onboarding report checks |
 | `lib/cli/project-scaffolder/**` | high | Preserve docs-first and design-contract behavior without hardcoded house style | design/detection smoke tests, validation |
 | `scripts/validate*.mjs`, `scripts/validate/**` | high | Keep validation mechanical and aligned with current shipped surfaces | `node ./scripts/validate.mjs`, targeted script checks |
@@ -35,6 +35,6 @@ Use this file as repo-local agent context. It records the current governance arc
 
 1. Load the smallest relevant rule set.
 2. Use README only for public and developer overview, setup, usage, and user-facing context when governance files conflict.
-3. Preserve generated adapter sync before release.
+3. Preserve native import bridge sync before release.
 4. Treat stale generated state, dual lockfiles, and obsolete V2/V3 transition files as cleanup findings.
 5. Before claiming done, run the relevant validation gate and report any skipped checks.

package/.agent-context/state/dependency-map.md

@@ -21,7 +21,7 @@ Use this map to keep Agentic-Senior-Core's CLI, governance, and validation layer
 | `lib/cli/commands/upgrade.mjs` | detector, compiler, scaffolder seeds, backup/rollback, shared setup helpers | duplicated setup-policy helpers, silent stack migration |
 | `lib/cli/project-scaffolder.mjs` | stable public scaffolder exports | private validation helpers that do not need public API exposure |
 | `lib/cli/project-scaffolder/design-contract.mjs` | validation submodule, constants, utilities | hardcoded final palettes, fixed layouts, external design memory |
-| `scripts/sync-thin-adapters.mjs` | canonical instructions and adapter targets | hand-maintained duplicate policy blocks |
+| `scripts/sync-thin-adapters.mjs` | `AGENTS.md` and native import bridge targets | hand-maintained duplicate policy blocks |
 | `scripts/validate*.mjs` | config, coverage checks, file evidence | stale V2 skill-marketplace artifacts |
 | `.agent-context/prompts/bootstrap-design.md` | current repo evidence and frontend rule | prior-chat visuals, unrelated screenshots, template style presets |
 
@@ -30,7 +30,7 @@ Use this map to keep Agentic-Senior-Core's CLI, governance, and validation layer
 - Reject `commands -> project-scaffolder -> commands`.
 - Reject `compiler -> commands`.
 - Reject `scripts/validate -> tests`.
-- Reject generated adapters becoming inputs for `.instructions.md` or `.agent-context/`.
+- Reject generated adapters becoming inputs for `AGENTS.md` or `.agent-context/`.
 - Move repeated command setup policy into shared helper modules instead of copying local functions.
 
 ## Package Hygiene

package/AGENTS.md

@@ -1,44 +1,179 @@
-# AGENTS.md - Thin Adapter
+# Agentic-Senior-Core: Unified AI Agent Instructions
 
-Adapter Mode: thin
-Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
+Canonical project instructions. Resolve the smallest relevant layer set for the current request.
 
+## Role
+Act as a Principal Engineer. Ship maintainable, validated, production-ready work. Use clear plain language in formal artifacts. Do not use emoji.
+
+## Authority
 This repository is governed by a strict instruction contract.
-Use [.instructions.md](.instructions.md) as the canonical policy source.
-Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
-
-## Critical Bootstrap Floor
-
-- If your host stops at this file, continue the chain manually before coding.
-- Read `.agent-instructions.md` next when it exists.
-- Memory continuity does not replace bootstrap loading.
-- For UI, UX, layout, screen, tailwind, frontend, or redesign requests, load [bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before code edits.
-- For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
-- For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
-- For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
-- Create or refine root README.md as the public and developer entrypoint before implementation.
-- For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
-- For ecosystem, framework, dependency, or Docker claims, perform live web research.
-- Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.
-
-## Mandatory Bootstrap Chain
-
-1. Load [.instructions.md](.instructions.md).
-2. Load `.agent-instructions.md` when present.
-3. Load only relevant files from .agent-context/rules/ ([link](.agent-context/rules)).
-4. Apply matching prompts from .agent-context/prompts/ ([link](.agent-context/prompts)).
-5. Enforce .agent-context/review-checklists/ ([link](.agent-context/review-checklists/pr-checklist.md)).
-6. Use .agent-context/state/ ([link](.agent-context/state)) and .agent-context/policies/ ([link](.agent-context/policies)) only when relevant.
-7. Use project docs and live evidence for runtime, dependency, and architecture claims.
+
+Use `AGENTS.md` as the canonical baseline. Use `.agent-context/` as technical authority for rules, prompts, checklists, state, and policies. Use `README.md` only for public and developer overview, setup, usage, and user-facing context when stricter governance files conflict.
+
+Write instructions as imperative gates:
+- Use direct commands.
+- Prefer short mechanical checks over descriptive prose.
+- Keep root adapters thin.
+- Move detailed policy into `.agent-context/`.
+- Add validation when a rule can drift.
 
 ## Bootstrap Receipt
+For non-trivial coding, review, planning, or governance work, emit a concise Bootstrap Receipt before implementation output or file edits:
+- `loaded_files`: files actually read
+- `selected_rules`: files selected for this scope and why
+- `skipped_rules`: out-of-scope categories left unloaded
+- `unreachable_files`: required files that could not be read
+- `validation_plan`: expected checks before completion
+
+Keep it short. Do not load every rule just to fill it out.
+
+## Command Economy
+Avoid repeated command output. Do not rerun broad inspections unless edits changed the result. Prefer targeted reads, targeted searches, concise diffs, and final validation gates.
+
+## Layer Index
+### Layer 1: Rules (15 Files) [SCOPE-RESOLVED]
+Location: `.agent-context/rules/`.
+
+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. Also perform live web research for Docker and framework/package setup claims. 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`.
+- Endpoint/API/error contracts: `architecture.md`, `api-docs.md`, `error-handling.md`, `security.md`, `testing.md`.
+- Auth/secrets/uploads/permissions: `security.md`, `error-handling.md`, `testing.md`.
+- Queue/worker/cron/events/retry: `event-driven.md`, `database-design.md`, `error-handling.md`, `performance.md`, `testing.md`.
+- Multi-service/distributed boundaries: `microservices.md`, `event-driven.md`, `database-design.md`, `api-docs.md`, `architecture.md`.
+
+Use the union once when scopes overlap. Do not create framework-specific governance adapters.
+
+### Layer 2: Runtime Decision Signals
+
+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. 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. 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
+
+Execution Contracts are dynamic execution contracts from prompts, review checklists, and policy thresholds. Resolve the active contract, then enforce mandatory checks before declaring completion.
+
+### Layer 5: Prompts
+
+Location: `.agent-context/prompts/`.
+
+Load the matching prompt only:
+- `init-project.md` -> create, build, new project, scaffold
+- `refactor.md` -> refactor, improve, clean up, fix
+- `review-code.md` -> review, audit, check, analyze
+- `bootstrap-design.md` -> ui, ux, layout, screen, tailwind, frontend, redesign
+
+For UI-only work, load `bootstrap-design.md` and `frontend-architecture.md` first; do not eagerly load unrelated backend-only rules unless the request crosses that boundary. The valid style context is current repo evidence, current brief, and current project docs. External references, prior-chat memory, unrelated-project visuals, and remembered screenshots are tainted unless the user makes them current-task constraints. Treat WCAG 2.2 AA as the hard compliance floor and APCA as advisory perceptual tuning only. Do not require screenshot capture as a baseline dependency.
+
+### Layer 6: Governance Modes
+
+Governance Modes use dynamic governance context from state files, policies, and repo norms. Apply matching defaults only when relevant.
+
+### Layer 7: State and Benchmarks
+
+Use `.agent-context/state/` only when the task needs risk zones, dependency boundaries, benchmarks, or continuity metadata. For initialized projects, `.agent-context/state/onboarding-report.json` records selected profile, runtime evidence, architecture decision status, token optimization, and memory continuity.
+
+### Layer 8: Policies and Thresholds
+
+Use `.agent-context/policies/` for quality gates, release thresholds, and audit posture.
+
+### Layer 9: Project Context
+
+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
+
+### 1. Documentation-First Mode
+
+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/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; do not write application, firmware, or UI code before approval.
+
+### 2. New Project Planning
+
+Trigger: create, build, new project, scaffold.
+
+1. Resolve relevant rules.
+2. Read `init-project.md`.
+3. Infer constraints, required docs, and boundaries from requirements, repo evidence, docs, and live research.
+4. Recommend runtime/architecture when unresolved.
+5. WAIT for user approval before generating code.
+
+### 3. Refactor Mode
+
+Trigger: refactor, improve, fix, clean up.
+
+1. Resolve relevant rules.
+2. Read `refactor.md`.
+3. Apply active prompt/checklist contracts.
+4. Propose a plan before edits.
+5. WAIT for approval.
+
+### 4. Code Review Mode
+
+Trigger: review, audit, check, analyze.
+
+Load `pr-checklist.md` and `architecture-review.md`, then report defects, risks, regressions, and missing tests first.
+
+### 5. UI Design Mode
+
+Trigger: ui, ux, layout, screen, tailwind, frontend, redesign.
+
+1. Read `bootstrap-design.md` and `frontend-architecture.md`.
+2. Read UI-relevant repo evidence from state, current UI code, and `docs/*`.
+3. Include a one-line Motion/Palette Decision before UI code; product categories are heuristics, not style presets.
+4. Before UI code, record one real-world anchor, one signature motion behavior, and one typographic role contrast.
+5. Ensure `docs/design-intent.json` includes `conceptualAnchor.anchorReference`, top-level `derivedTokenLogic`, `libraryResearchStatus`, `libraryDecisions[]`, and motion/palette decisions.
+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
+
+When rejecting an approach or enforcing a rule, use:
+
+```text
+REASONING CHAIN
+Problem: [risk]
+Required Action: [boundary]
+Why Required: [project protection]
+```
+
+## Definition of Done
+
+Never claim done without:
+1. Relevant rules applied.
+2. PR and architecture checklists considered.
+3. Universal SOP gates satisfied: public and developer root `README.md`; `docs/architecture-decision-record.md`; plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
+4. If `.agent-context/state/active-memory.json` exists and material project progress happened, refresh it while preserving privacy rules and user-owned entries.
+5. MCP validation passed through `npm run validate`.
 
-For non-trivial coding, review, planning, or governance work, produce a short Bootstrap Receipt before implementation output: `loaded_files`, `selected_rules`, `skipped_rules`, `unreachable_files`, and `validation_plan`.
+## Knowledge Inventory Checklist
 
-## Completion Gate
+Verify reachability when relevant: Layer 1 Rules, Layer 2 Runtime Decision Signals, Layer 3 Structural Planning Signals, Layer 4 Execution Contracts, Layer 5 Prompts, Layer 6 Governance Modes, Layer 7 State, Layer 8 Policies, Layer 9 Project Context.
 
-Run [pr-checklist.md](.agent-context/review-checklists/pr-checklist.md) before declaring work complete.
+## Operating Gates
 
-If this adapter drifts from canonical behavior, refresh from [.instructions.md](.instructions.md) and update the hash metadata.
+- Before code: resolve active rules and contract.
+- Before PR: run review checklists.
+- Before deploy: check policy thresholds.
+- Before major refactor: read `architecture-map.md`.
+- Before UI implementation: confirm valid style context, design contract, and required docs.

package/CLAUDE.md

@@ -1,44 +1 @@
-# CLAUDE.md - Thin Adapter
-
-Adapter Mode: thin
-Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
-
-This repository is governed by a strict instruction contract.
-Use [.instructions.md](.instructions.md) as the canonical policy source.
-Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
-
-## Critical Bootstrap Floor
-
-- If your host stops at this file, continue the chain manually before coding.
-- Read `.agent-instructions.md` next when it exists.
-- Memory continuity does not replace bootstrap loading.
-- For UI, UX, layout, screen, tailwind, frontend, or redesign requests, load [bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before code edits.
-- For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
-- For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
-- For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
-- Create or refine root README.md as the public and developer entrypoint before implementation.
-- For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
-- For ecosystem, framework, dependency, or Docker claims, perform live web research.
-- Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.
-
-## Mandatory Bootstrap Chain
-
-1. Load [.instructions.md](.instructions.md).
-2. Load `.agent-instructions.md` when present.
-3. Load only relevant files from .agent-context/rules/ ([link](.agent-context/rules)).
-4. Apply matching prompts from .agent-context/prompts/ ([link](.agent-context/prompts)).
-5. Enforce .agent-context/review-checklists/ ([link](.agent-context/review-checklists/pr-checklist.md)).
-6. Use .agent-context/state/ ([link](.agent-context/state)) and .agent-context/policies/ ([link](.agent-context/policies)) only when relevant.
-7. Use project docs and live evidence for runtime, dependency, and architecture claims.
-
-## Bootstrap Receipt
-
-For non-trivial coding, review, planning, or governance work, produce a short Bootstrap Receipt before implementation output: `loaded_files`, `selected_rules`, `skipped_rules`, `unreachable_files`, and `validation_plan`.
-
-## Completion Gate
-
-Run [pr-checklist.md](.agent-context/review-checklists/pr-checklist.md) before declaring work complete.
-
-If this adapter drifts from canonical behavior, refresh from [.instructions.md](.instructions.md) and update the hash metadata.
+@AGENTS.md

package/CONTRIBUTING.md

@@ -13,7 +13,6 @@ Thanks for wanting to make AI agents write better code. Here's how to contribute
 | Structural planning guidance update | `.agent-context/prompts/`, `lib/cli/compiler.mjs` | Scope planning, docs bootstrap, and project-context guidance |
 | New checklist | `.agent-context/review-checklists/` | Self-audit guide |
 | State intelligence update | `.agent-context/state/` | Architecture boundaries and dependency map |
-| Override policy update | `.agent-override.md` | Scoped rule exceptions |
 | MCP workflow update | `mcp.json` | Self-healing automation flow |
 | Bug fix | Any file | Typos, broken links, incorrect rules |
 | Improvement | Any file | Sharper wording, stricter boundaries |
@@ -63,7 +62,7 @@ If all three are "yes", it belongs here.
    - Core principle (1-2 sentences)
    - BANNED / REQUIRED sections with enforceable boundaries
    - Decision tree or quick ruleset when it reduces ambiguity
-3. Update `.instructions.md` or `.agent-context/` as the source, then regenerate thin adapters with `npm run sync:adapters`
+3. Update `AGENTS.md` or `.agent-context/` as the source, then verify thin adapters with `npm run check:adapters`
 4. Update `review-checklists/pr-checklist.md` when the rule is part of review scope
 5. Validate and PR
 
@@ -88,7 +87,7 @@ If all three are "yes", it belongs here.
 - Generic content that reads like it was auto-generated without thought
 - Rules without concrete enforcement boundaries
 - Stack profiles for languages the author doesn't actually use in production
-- PRs that don't update the relevant source files, generated adapters, and checklists
+- PRs that don't update the relevant source files, docs, validators, and checklists
 
 ---
 

package/GEMINI.md

@@ -1,44 +1 @@
-# GEMINI.md - Thin Adapter
-
-Adapter Mode: thin
-Adapter Source: .instructions.md
-Canonical Snapshot SHA256: c66b5dfe48a25f0df297a1681aa6bab572da95d2201f09abf3767d38a2934591
-
-This repository is governed by a strict instruction contract.
-Use [.instructions.md](.instructions.md) as the canonical policy source.
-Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
-
-## Critical Bootstrap Floor
-
-- If your host stops at this file, continue the chain manually before coding.
-- Read `.agent-instructions.md` next when it exists.
-- Memory continuity does not replace bootstrap loading.
-- For UI, UX, layout, screen, tailwind, frontend, or redesign requests, load [bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before code edits.
-- For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
-- For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
-- For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
-- Create or refine root README.md as the public and developer entrypoint before implementation.
-- For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
-- For ecosystem, framework, dependency, or Docker claims, perform live web research.
-- Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.
-
-## Mandatory Bootstrap Chain
-
-1. Load [.instructions.md](.instructions.md).
-2. Load `.agent-instructions.md` when present.
-3. Load only relevant files from .agent-context/rules/ ([link](.agent-context/rules)).
-4. Apply matching prompts from .agent-context/prompts/ ([link](.agent-context/prompts)).
-5. Enforce .agent-context/review-checklists/ ([link](.agent-context/review-checklists/pr-checklist.md)).
-6. Use .agent-context/state/ ([link](.agent-context/state)) and .agent-context/policies/ ([link](.agent-context/policies)) only when relevant.
-7. Use project docs and live evidence for runtime, dependency, and architecture claims.
-
-## Bootstrap Receipt
-
-For non-trivial coding, review, planning, or governance work, produce a short Bootstrap Receipt before implementation output: `loaded_files`, `selected_rules`, `skipped_rules`, `unreachable_files`, and `validation_plan`.
-
-## Completion Gate
-
-Run [pr-checklist.md](.agent-context/review-checklists/pr-checklist.md) before declaring work complete.
-
-If this adapter drifts from canonical behavior, refresh from [.instructions.md](.instructions.md) and update the hash metadata.
+@AGENTS.md