@ryuenn3123/agentic-senior-core 3.0.44 → 3.0.45

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

@@ -8,7 +8,7 @@ This contract is a decision scaffold, not a style preset. We guide the agent; we
 
 ## Authority
 - Treat `.agent-context/` and current project docs as technical authority.
-- Treat `README.md` as overview, install, and user-facing context only. Do not use it as coding, architecture, or design authority when `.agent-context/` gives a stricter rule.
+- 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.
 - Use current repo evidence, product copy, route names, component names, user goals, and existing constraints as the source of truth.
 - 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.

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

@@ -25,9 +25,12 @@ 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: `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/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. 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 `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.
 
 ## Direct Constraint Mode
 

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 `docs/architecture-decision-record.md` is missing, and for UI scope stop 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/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 (`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/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

@@ -60,7 +60,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: project brief, architecture decision, flow overview, API/public contract when relevant, data model when relevant, and UI design contract when relevant.
+- [ ] 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.
 - [ ] 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.
@@ -70,6 +70,9 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] Facts, assumptions, and next actions are separated when context is incomplete.
 - [ ] No emoji in formal documentation or review summaries
 - [ ] Documentation uses plain English and avoids AI cliches
+- [ ] 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.
 
 ## 7. UI And Accessibility
 
@@ -116,6 +119,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] `.agent-context/rules/` remains the default guidance source for implementation and review.
 - [ ] 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
 - [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing
 
 ## Verdict

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

@@ -4,6 +4,22 @@
 
 If a change affects an API, CLI command, exported library behavior, schema, event, or integration contract, update the matching docs in the same change.
 
+## Public README Boundary
+
+Root `README.md` is required for every fresh or existing project. This includes private projects, because a future maintainer still needs a clear public and developer entrypoint.
+
+README content must be safe for outside readers and useful for developers. It must explain what the project is, who it is for, how to set it up, how to run the main workflow, how to configure it, and where deeper docs live when those topics apply.
+
+Keep README overview-level. Do not make it the canonical governance source. Do not put secrets, private agent notes, hidden reasoning, backlog chatter, raw architecture debate, or internal policy dumps in it.
+
+Choose README sections from project evidence. Do not force a fixed template when a section does not apply. For private/internal projects, keep the same clear style but omit private URLs, credentials, customer names, and internal-only operational details that do not belong in repo docs.
+
+## Documentation Growth Model
+
+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.
+
+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.
+
 ## Contract Rules
 
 - Document the public surface before or alongside implementation.

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

@@ -32,17 +32,20 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Backend and frontend mindset checks are both required when a task spans API and UI boundaries.
 - 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/project-brief.md` must exist.
   - `docs/architecture-decision-record.md` (alias: `docs/Architecture-Decision-Record.md`) must exist.
   - `docs/flow-overview.md` must exist.
   - If the project uses persistent data, `docs/database-schema.md` must exist.
   - If the project exposes API or web application flows, `docs/api-contract.md` must exist.
   - For UI scope, `docs/DESIGN.md` and `docs/design-intent.json` must exist.
-- Required docs coverage must include feature plan, architecture rationale, public contracts, data model when relevant, UI/design when relevant, security assumptions, testing strategy, delivery flow, and next validation actions.
+- Required docs coverage must include a public and developer README entrypoint, feature plan, architecture rationale, public contracts, data model when relevant, UI/design when relevant, security assumptions, testing strategy, delivery flow, and next validation actions.
 - If required project context docs are missing, stop implementation and bootstrap docs before writing application code.
 - Bootstrap flow: analyze the real repo plus the latest user prompt before authoring those docs.
 - Bootstrap docs must be adaptive and project-specific. Do not create generic placeholder templates.
 - When context is incomplete, separate confirmed facts from assumptions, add an `Assumptions to Validate` section, and end with the next validation action.
+- 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.
 
 ## Rules as Guardian (Cross-Session Consistency)
 

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

@@ -10,7 +10,7 @@ Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, f
 
 - Use current repo evidence, the active brief, and current project docs as valid style context.
 - Treat `.agent-context/` as design governance authority.
-- Treat `README.md` as overview/install/user context only when design or architecture rules conflict.
+- 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.

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

@@ -34,7 +34,7 @@ Use this file as repo-local agent context. It records the current governance arc
 ## Agent Behavior
 
 1. Load the smallest relevant rule set.
-2. Use README only for overview/install/user context when governance files conflict.
+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.
 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/.cursor/rules/agentic-senior-core.mdc

@@ -7,12 +7,12 @@ alwaysApply: true
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -23,6 +23,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

package/.cursorrules

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

package/.gemini/instructions.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

package/.github/copilot-instructions.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

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

@@ -6,12 +6,12 @@ applyTo: "**"
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -22,6 +22,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

package/.instructions.md

@@ -10,7 +10,7 @@ Act as a Principal Engineer. Ship maintainable, validated, production-ready work
 
 This repository is governed by a strict instruction contract.
 
-Use `.instructions.md` as the canonical baseline. Use `.agent-context/` as technical authority for rules, prompts, checklists, state, and policies. Use `README.md` only for overview, setup, and user-facing context when stricter governance files conflict.
+Use `.instructions.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.
@@ -97,7 +97,7 @@ Use `.agent-context/policies/` for quality gates, release thresholds, and audit
 
 ### Layer 9: Project Context
 
-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/` 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,7 +106,7 @@ Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`,
 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: `docs/project-brief.md`, `docs/architecture-decision-record.md`, `docs/flow-overview.md`, `docs/api-contract.md` for APIs/firmware/CLI/web flows, `docs/database-schema.md` for persistent data, and `docs/DESIGN.md` plus `docs/design-intent.json` for UI 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.
 
@@ -165,7 +165,7 @@ Why Required: [project protection]
 Never claim done without:
 1. Relevant rules applied.
 2. PR and architecture checklists considered.
-3. Universal SOP gates satisfied: `docs/architecture-decision-record.md`, plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
+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`.
 

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

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

package/.windsurfrules

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

package/AGENTS.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

package/CLAUDE.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

package/GEMINI.md

@@ -2,12 +2,12 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 8a232b1dc9792849a9290898ef40dfff730c13cd0b443d217c0590ced04ed946
+Canonical Snapshot SHA256: a64819c73c12f55405e4e6249b352fbdb8b94847bc43279e8bf43e07ef5357f3
 
 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 overview/install/user context only when governance files conflict.
+Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
 
 ## Critical Bootstrap Floor
 
@@ -18,6 +18,7 @@ Treat README.md as overview/install/user context only when governance files conf
 - 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.

package/lib/cli/compiler.mjs

@@ -422,7 +422,9 @@ 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: 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/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.',
+      '- 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.',
       'UI trigger policy:',
@@ -543,6 +545,7 @@ export async function buildCompiledRulesContent({
   const hasBootstrapDesignPrompt = await pathExists(bootstrapDesignPromptPath);
 
   if (await pathExists(projectBriefPath)) {
+    const hasRootReadme = await pathExists(path.join(resolvedTargetDirectoryPath, 'README.md'));
     const projectDocsEntries = ['project-brief.md'];
     const candidateDocFileNames = [
       'architecture-decision-record.md',
@@ -565,15 +568,18 @@ export async function buildCompiledRulesContent({
         '## LAYER 9: PROJECT CONTEXT (MANDATORY)',
         'These documents describe the specific project being built.',
         'Read them before writing any application code:',
-        ...projectDocsEntries.map((docFileName, docIndex) => `${docIndex + 1}. docs/${docFileName}`),
+        ...(hasRootReadme ? ['1. README.md'] : []),
+        ...projectDocsEntries.map((docFileName, docIndex) => `${(hasRootReadme ? 2 : 1) + docIndex}. docs/${docFileName}`),
         '',
         'Universal SOP hard block policy:',
+        '- README.md must exist and read as a public and developer entrypoint.',
         '- 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.',
         '- If the product uses persistent data, docs/database-schema.md must exist before coding continues.',
         '- 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.',
         '- 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.',
@@ -583,7 +589,7 @@ export async function buildCompiledRulesContent({
         'Latest user prompt defines current feature scope and product direction.',
         'Treat requested features as dynamic, but keep stack/database/auth constraints consistent',
         'with project docs unless the user explicitly asks for a migration.',
-        'When scope changes, implement the new request and update docs/* in the same change',
+        'When scope changes, implement the new request and update README.md plus docs/* in the same change when documented context changes',
         'so generated context stays aligned with the codebase.',
         'Update them as the project evolves. They are living references, not frozen specs.',
       ].join('\n')
@@ -605,6 +611,7 @@ export async function buildCompiledRulesContent({
         ...bootstrapPromptEntries.map((promptFilePath, promptIndex) => `${promptIndex + 1}. ${promptFilePath}`),
         '',
         'Bootstrap policy:',
+        '- Create README.md as a public and developer entrypoint before coding continues.',
         '- 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.',

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

@@ -44,8 +44,11 @@ export function buildProjectContextBootstrapPrompt({
     ? discoveryAnswers.features.map((feature, featureIndex) => `${featureIndex + 1}. ${feature}`).join('\n')
     : 'Derive the first concrete feature set from the project name, description, and domain. Do not invent arbitrary modules just to fill space.';
 
-  const expectedDocsList = expectedDocFileNames
-    .map((fileName, fileIndex) => `${fileIndex + 1}. docs/${fileName}`)
+  const expectedDocsList = [
+    'README.md',
+    ...expectedDocFileNames.map((fileName) => `docs/${fileName}`),
+  ]
+    .map((filePath, fileIndex) => `${fileIndex + 1}. ${filePath}`)
     .join('\n');
 
   return [
@@ -73,7 +76,9 @@ export function buildProjectContextBootstrapPrompt({
     '10. Do not invent modules or architecture layers only to make the docs look complete.',
     '11. If runtime or framework setup is unresolved, recommend the latest stable compatible option from the brief, constraints, and live official documentation before coding. If an official setup flow yields newer, better-supported defaults than manual package assembly, use that path after approval.',
     '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 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.',
+    '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.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -101,8 +106,9 @@ export function buildProjectContextBootstrapPrompt({
     '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. Keep content original, specific to this project, and actionable for implementation.',
-    '5. After writing docs, continue coding tasks using these docs as living project context.',
+    '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.',
     '',
   ].join('\n');
 }

package/package.json

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

package/scripts/frontend-usability-audit.mjs

@@ -58,7 +58,7 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   '## Activation',
   '## Authority',
   'Treat `.agent-context/` as design governance authority.',
-  'Treat `README.md` as overview/install/user context only',
+  'Treat `README.md` as public and developer overview, setup, usage, and user-facing context only',
   'Do not choose final style, framework, palette, typography, layout paradigm, or animation library offline.',
   'Keep design continuity opt-in.',
   'Repo evidence outranks memory residue.',

package/scripts/sync-thin-adapters.mjs

@@ -59,7 +59,7 @@ function buildThinAdapter({
     'This repository is governed by a strict instruction contract.',
     `Use [${CANONICAL_SOURCE_PATH}](${canonicalLink}) as the canonical policy source.`,
     'Use .agent-context/ for technical rules, prompts, checklists, policies, and state.',
-    'Treat README.md as overview/install/user context only when governance files conflict.',
+    'Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.',
     '',
     '## Critical Bootstrap Floor',
     '',
@@ -70,6 +70,7 @@ function buildThinAdapter({
     '- 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](${rulesLink})).`,
     '- 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.',

package/scripts/validate/config.mjs

@@ -195,6 +195,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     path: '.instructions.md',
     snippets: [
       '### 1. Documentation-First Mode',
+      'root `README.md` for every fresh or existing project',
       'Stop after documentation when the user only asked for docs.',
       'Do not write application, firmware, or UI code',
     ],
@@ -203,6 +204,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     path: '.agent-context/rules/architecture.md',
     snippets: [
       '## Universal SOP Baseline (Mandatory)',
+      'Root `README.md` must exist for every fresh or existing project',
       'Security and testing are non-negotiable baseline requirements.',
       'If required project context docs are missing, stop implementation and bootstrap docs before writing application code.',
     ],
@@ -211,6 +213,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     path: '.agent-context/prompts/init-project.md',
     snippets: [
       '## Documentation-First Requests',
+      'root `README.md` for every fresh or existing project',
       'Stop after docs when the user only asked for docs.',
       'Write formal project docs in English by default',
     ],
@@ -219,6 +222,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     path: '.agent-context/review-checklists/pr-checklist.md',
     snippets: [
       '### 15. Universal SOP Consolidation',
+      'Coding flow is blocked if root `README.md` is missing',
       'Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing',
       'UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing',
     ],
@@ -226,21 +230,23 @@ 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 (`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/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 `docs/architecture-decision-record.md` is missing, and for UI scope stop 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/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:',
+      '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:',
+      'Keep README.md public and developer friendly',
       'For docs-only/docs-first requests, do not write application, firmware, or UI code until the user asks or approves an implementation plan.',
       'For UI scope: if docs/DESIGN.md or docs/design-intent.json is missing, execute bootstrap-design prompt before implementing UI surfaces.',
     ],