@ryuenn3123/agentic-senior-core 2.0.4 → 2.0.5

package/README.md

@@ -1,368 +1,368 @@
-<div align="center">
-
-# Agentic-Senior-Core
-
-### Force your AI Agent to code like a Staff Engineer, not a Junior.
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
-
-**Universal engineering standards for AI coding agents.**
-Works with Cursor · Windsurf · GitHub Copilot · Claude Code · Gemini · Any LLM-powered IDE.
-
-</div>
-
----
-
-## What is This?
-
-This is **not** a boilerplate. It's a **dynamic governance engine**: strict engineering rules, stack profiles, blueprints, review checklists, override policies, and state maps that keep AI output production-grade.
-
-Think of it as giving your AI pair programmer **10 years of production experience** through carefully crafted instructions and guardrails.
-
-### Before Agentic-Senior-Core
-```text
-You: "Build me a user registration API"
-AI:  *Creates a single file with no validation, any types, console.log,
-      hardcoded secrets, no error handling, and 47 TODO comments*
-```
-
-### After Agentic-Senior-Core
-```text
-You: "Build me a user registration API"
-AI:  *Creates properly layered modules with Zod validation, typed errors,
-      structured logging, security headers, tests, and API documentation*
-```
-
----
-
-## Quick Start
-
-### Zero-Install: GitHub Template (New user friendly!)
-
-The absolute fastest way to start your next top-tier project is to use this repository as a template.
-The **Use this template** button is in the GitHub repository header (top-right area), not inside this README text.
-If you prefer a direct link, open: **[Create from template](https://github.com/fatidaprilian/Agentic-Senior-Core/generate)**.
-Your new repository will instantly possess all the rules, configurations, and AI context files directly out of the box — zero CLI needed.
-
-### Option 0: NPM Install (Local or Global)
-
-If you already know you want the CLI from npm, use one of these paths:
-
-```bash
-npm exec --yes @ryuenn3123/agentic-senior-core init
-npm install -g @ryuenn3123/agentic-senior-core
-agentic-senior-core init
-```
-
-### Option 1: Interactive via GitHub Source (Pre-publish friendly)
-
-If npm package publication is not ready yet, run the CLI directly from GitHub and still keep the full interactive experience.
-
-```bash
-npm exec --yes --package=github:fatidaprilian/Agentic-Senior-Core agentic-senior-core init .
-```
-
-This gives the same interactive prompts to choose your profile (`beginner`, `balanced`, `strict`), stack, blueprint, and CI guardrails.
-
-If you want a plug-and-play starter instead of answering every question, use a preset:
-
-```bash
-npx @ryuenn3123/agentic-senior-core init --preset frontend-web
-npx @ryuenn3123/agentic-senior-core init --preset backend-api
-npx @ryuenn3123/agentic-senior-core init --preset mobile-react-native
-```
-
-### Option 2: GitHub Bootstrap Scripts (No npx required)
-
-Run directly from this repository bootstrap script and inject rules into your project root.
-
-Bootstrap script paths: `scripts/init-project.ps1` (Windows) and `scripts/init-project.sh` (Linux/macOS).
-
-Windows PowerShell:
-
-```powershell
-powershell -ExecutionPolicy Bypass -File .\scripts\init-project.ps1 -TargetDirectory . -Profile balanced -Stack typescript -Blueprint api-nextjs -Ci true
-```
-
-Linux/macOS Bash:
-
-```bash
-bash ./scripts/init-project.sh . --profile balanced --stack typescript --blueprint api-nextjs --ci true
-```
-
-Both scripts clone Agentic-Senior-Core into a temporary directory, run the same CLI engine, then clean up automatically.
-
-If you want interactive selection, omit `-Profile`, `-Stack`, `-Blueprint`, and `-Ci` on the script command.
-
-### Option 3: Interactive Auto-Setup via npm/npx (Post-publish)
-
-If you have an existing project and want to infuse it with Staff-level context:
-
-```bash
-npx @ryuenn3123/agentic-senior-core init
-```
-
-Use team defaults (V2.0 track) with profile packs:
-
-```bash
-npx @ryuenn3123/agentic-senior-core init --profile-pack startup
-```
-
-The CLI is smart. It auto-detects your current development stack, helps you build a governance profile (select from `beginner`, `balanced`, or `strict`), and writes the compiled rules straight to your root automatically!
-
-If you are totally new to concepts like blueprints and guardrails, no problem — just run:
-```bash
-npx @ryuenn3123/agentic-senior-core init --newbie
-```
-
-### Skill Selector
-
-Use the unified skill selector to pick the right pack for a domain:
-
-```bash
-agentic-senior-core skill frontend --tier advance
-agentic-senior-core skill backend --tier expert
-agentic-senior-core skill fullstack --json
-```
-
-When you run `init`, the CLI now auto-activates the matching skill packs for the chosen stack and blueprint, so the compiled governance context includes the relevant frontend, backend, fullstack, and CLI guidance by default.
-
-### Token Optimization Mode (Enabled by Default on Init)
-
-Use this mode when your AI session is shell-heavy and context usage is high.
-By default, every `init` flow enables token optimization automatically (npx, npm exec, global CLI, preset, and interactive wizard).
-The optimization engine works in two modes:
-- Native fallback mode (no external dependency required)
-- External proxy mode (auto-detected when available)
-
-Quick start:
-
-```bash
-agentic-senior-core optimize . --agent copilot --enable
-agentic-senior-core optimize . --show
-agentic-senior-core optimize . --disable
-
-# Auto-enable during project initialization
-npx @ryuenn3123/agentic-senior-core init --token-optimize --token-agent copilot
-
-# Opt out when needed
-npx @ryuenn3123/agentic-senior-core init --no-token-optimize
-```
-
-When enabled, the CLI writes `.agent-context/state/token-optimization.json`, regenerates compiled rules, and adds compact command guidance to `.cursorrules` and `.windsurfrules`.
-If an external token proxy is available, the CLI prints setup hints. If not, native fallback guidance stays active, so outside users are not forced to install extra tooling.
-
-### Token Efficiency Benchmark Snapshot
-
-Latest local benchmark (2026-04-11) from `.agent-context/state/token-optimization-benchmark.json`:
-
-| Scenario | Baseline Token Estimate | Agentic Native Token Estimate | Native Savings | RTK Token Estimate | RTK Status |
-|----------|-------------------------|-------------------------------|----------------|--------------------|------------|
-| Latest commit detail review | 3798 | 177 | 95.34% | 3798 | Detected (`rtk` v0.35.0) |
-| Commit history review | 3730 | 889 | 76.17% | 1610 | Detected (`rtk` v0.35.0) |
-| Search result scan | 5339 | 1099 | 79.42% | 5339 | Detected (`rtk` v0.35.0) |
-| Average | - | - | 83.64% | 18.95% savings | Detected (`rtk` v0.35.0) |
-
-Method note:
-- Estimate formula is `ceil(output_chars / 4)`.
-- This is a command-output estimate, not provider-specific tokenizer output.
-- RTK results depend on host utilities. On Windows hosts without GNU `grep` or `ls`, RTK may fall back to `rtk git ...` paths for some scenarios.
-
-Reproduce and refresh this table:
-
-```bash
-npm run benchmark:token
-```
-
-### Install and Setup Choices
-
-The CLI now supports a smaller decision surface for first-time setup:
-
-| Path | Best for |
-|------|----------|
-| `agentic-senior-core launch` | Numbered interactive chooser for install and preset paths |
-| GitHub Template | Zero-install project bootstrap |
-| npm exec / npx | One-off setup on an existing repo |
-| npm install -g | Repeated local use from the shell |
-| `--preset` | Fast bootstrap with a curated stack and blueprint |
-| `optimize` | Optional token-aware shell output guidance with native fallback |
-
-### Supported Stack Map
-
-Use the stack that matches the project you are actually starting:
-
-| Stack | Recommended Blueprint | Best Fit |
-|-------|-----------------------|----------|
-| TypeScript | api-nextjs | Web app, fullstack product, CLI tooling |
-| Python | fastapi-service | API service, automation, data-heavy backend |
-| Go | go-service | Small, fast services and platform tooling |
-| Java | spring-boot-api | Enterprise APIs and service-oriented systems |
-| PHP | laravel-api | Conventional product backends |
-| C# | aspnet-api | Microsoft stack services and enterprise apps |
-| Rust | go-service | Performance-sensitive backend work |
-| Ruby | laravel-api | Mature product services and backend workflows |
-| React Native | mobile-app | Cross-platform mobile applications |
-| Flutter | mobile-app | Cross-platform mobile applications |
-
-### Benchmark Comparison (Current State)
-
-| Capability | antigravity-awesome-skills | awesome-copilot | MiniMax-AI/skills | Agentic-Senior-Core |
-|------------|----------------------------|-----------------|-------------------|---------------------|
-| Skill organization | Large curated library | Resource catalog + governance docs | Domain-focused packs | Unified folder-based domain packs with tier routing |
-| Architecture guidance | Strong practical patterns | Strong SoC and layered architecture | Strong applied templates | Consolidated architecture + domain enforcement |
-| CLI governance | Limited | Moderate | Moderate | Init/upgrade/output governance with dry-run and structured reports |
-| Distribution operations | Basic | Moderate | Strong release checklists | Publish, rollback, compatibility gates plus benchmark/sbom flows |
-| Review quality | Pattern-oriented | Checklist-oriented | Gate-oriented | Planning/security/benchmark review model with CI integration |
-
-### Option 4: Clone and Play
-Want to poke around under the hood? Just clone the repo and `npx @ryuenn3123/agentic-senior-core init` locally. No runtime dependencies needed — everything uses native Node.js!
-
-### Upgrade Existing Governance Packs (V1.x to V2.x)
-
-Yes, the upgrade flow still works. Use `--dry-run` first to preview changes, then apply with `--yes` when you are ready.
-
-Preview migration changes safely:
-
-```bash
-npx @ryuenn3123/agentic-senior-core upgrade --dry-run
-```
-
-Apply migration updates:
-
-```bash
-npx @ryuenn3123/agentic-senior-core upgrade --yes
-```
-
----
-
-## Further Reading
-
-Our documentation has shifted into dedicated tracks to keep this README light:
-- **[FAQ / Concepts](docs/faq.md)**: Unfamiliar with Stacks, Blueprints, or Guardrails? Stalled on basic logic? Start here.
-- **[Deep Dive / Internals](docs/deep-dive.md)**: Explore the dynamic compiler, severity profiles, MCP integration, and granular LLM overrides here.
-- **[V2 Upgrade Playbook](docs/v2-upgrade-playbook.md)**: Benchmark-driven upgrade execution from antigravity-awesome-skills, awesome-copilot, and MiniMax skills.
-- **[Skill Platform](.agent-context/skills/README.md)**: Unified skill packs for frontend, backend, fullstack, CLI, distribution, and review quality with `advance` as the default tier.
-      The skill platform is now folder-based, so each domain has its own README and topic docs like a curated skills library.
-
----
-
-## Core Capabilities
-
-- **Delivery Engine (CLI):** Interactive setup via GitHub source, bootstrap scripts, or `npx` after publish. Supported by a robust transactional installer with rollback protection.
-- **Verified Skill Marketplace:** Distribute and validate plugins securely with automated 4-dimension Trust Scoring and Evidence Bundles constraint validation.
-- **Dynamic Context Compiler:** Merges universal rules + selected stack + selected blueprint + optional CI guardrails into one dense, indexed rule file.
-- **Codebase Intelligence:** `.agent-context/state/` gives architecture/dependency boundaries so the agent understands high-risk areas.
-- **Override System:** `.agent-override.md` allows controlled enterprise exceptions without forking core rules.
-- **Automated Guardrails:** CI blueprints include LLM-as-a-Judge flow using `pr-checklist.md`.
-- **Pre-Publish Safety:** Built-in forbidden content checks detect hardcoded secrets and stray debugger artifacts before hitting the NPM registry.
-- **Machine-Readable CI Output:** LLM Judge emits `JSON_REPORT` payloads and writes `.agent-context/state/llm-judge-report.json` for PR/MR annotation tooling.
-- **MCP Self-Healing Loop:** `mcp.json` defines diagnostics + fix proposal workflow when lint/CI fails.
-
----
-
-## Repository Structure
-
-```text
-.
-├── .cursorrules                    # Dynamic compiled governance entry point
-├── .windsurfrules                  # Dynamic compiled governance entry point
-├── .agent-override.md              # Team-specific exceptions (scoped + expiry)
-├── mcp.json                        # MCP self-healing workflow config
-├── AGENTS.md                       # Universal agent discovery
-├── .github/copilot-instructions.md # GitHub Copilot entry point
-├── .gemini/instructions.md         # Antigravity / Gemini entry point
-├── bin/
-│   └── agentic-senior-core.js      # Interactive CLI (Delivery Engine)
-├── .agent-context/
-│   ├── rules/                      # Universal engineering laws
-│   ├── stacks/                     # Language-specific profiles
-│   ├── blueprints/                 # Scaffolding and pipeline templates
-│   ├── review-checklists/          # AI self-audit guides
-│   ├── prompts/                    # Ready-to-use prompts
-│   └── state/                      # Architecture and dependency state maps
-│       ├── architecture-map.md
-│       └── dependency-map.md
-├── scripts/
-│   ├── validate.mjs                # Repository validator
-│   ├── llm-judge.mjs               # LLM-as-a-Judge CI gate
-│   ├── init-project.sh             # GitHub bootstrap script (Linux/macOS)
-│   └── init-project.ps1            # GitHub bootstrap script (Windows)
-├── docs/
-│   ├── faq.md
-│   └── deep-dive.md
-├── tests/
-│   ├── cli-smoke.test.mjs
-│   └── llm-judge.test.mjs
-├── package.json
-├── CONTRIBUTING.md
-├── LICENSE
-└── README.md
-```
-
----
-
-## Validation
-
-Ensure everything is running smoothly before merging rules patches:
-
-```bash
-npm run validate
-```
-
-Track stack-detection KPI trends:
-
-```bash
-npm run benchmark:detection
-```
-
----
-
-## Roadmap
-
-### Completed Milestones
-- V1.0 to V1.3: Core rules, multi-language stacks, advanced architecture patterns, and infrastructure blueprints.
-- V1.4: Dynamic Governance Engine (interactive CLI, context compiler, state maps, override system, guardrails, MCP self-healing).
-- V1.5: Newbie-First Experience (Node-first runtime, zero-install onboarding path, smart auto-detection, profile presets, LLM severity thresholds, docs split, smoke tests).
-
-### V1.6 (Released) — Enterprise Reliability and Team Workflow
-- Team profile packs and safer override governance shipped.
-- CI annotation standardization and stronger detection transparency shipped.
-- Upgrade assistant and benchmark coverage shipped.
-
-### V1.7 (Released) — Frontend Product Experience Governance Pack
-- Frontend usability checklist, execution playbook, and issue template shipped.
-- Frontend usability audit script and CI artifact workflow shipped.
-
-### V1.8 (Released) — Enterprise Release Operations and Compliance
-- Release-gate automation shipped with machine-readable artifact output.
-- CycloneDX SBOM generation and compliance artifact workflow shipped.
-- Operations playbook and release-operations checklist shipped.
-
-### Current Forward Plan
-- V2.0: Skill marketplace trust tiers, transactional installs, rollback safety, and launch-menu onboarding.
-- V2.5: Cross-model benchmark harness and anti-regression quality gates.
-- V3.0: Enterprise governance cloud, policy drift detection, and org-level override registry.
-
-Detailed timeline and success metrics: [docs/roadmap.md](docs/roadmap.md)
-
----
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution standards and workflow.
-
----
-
-## License
-
-MIT — Use freely, enforce strictly.
-
----
-
-<div align="center">
-
-**Stop letting AI write junior code.**
-**Give it the rules of a Staff Engineer.**
-
-</div>
+<div align="center">
+
+# Agentic-Senior-Core
+
+### Force your AI Agent to code like a Staff Engineer, not a Junior.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+**Universal engineering standards for AI coding agents.**
+Works with Cursor · Windsurf · GitHub Copilot · Claude Code · Gemini · Any LLM-powered IDE.
+
+</div>
+
+---
+
+## What is This?
+
+This is **not** a boilerplate. It's a **dynamic governance engine**: strict engineering rules, stack profiles, blueprints, review checklists, override policies, and state maps that keep AI output production-grade.
+
+Think of it as giving your AI pair programmer **10 years of production experience** through carefully crafted instructions and guardrails.
+
+### Before Agentic-Senior-Core
+```text
+You: "Build me a user registration API"
+AI:  *Creates a single file with no validation, any types, console.log,
+      hardcoded secrets, no error handling, and 47 TODO comments*
+```
+
+### After Agentic-Senior-Core
+```text
+You: "Build me a user registration API"
+AI:  *Creates properly layered modules with Zod validation, typed errors,
+      structured logging, security headers, tests, and API documentation*
+```
+
+---
+
+## Quick Start
+
+### Zero-Install: GitHub Template (New user friendly!)
+
+The absolute fastest way to start your next top-tier project is to use this repository as a template.
+The **Use this template** button is in the GitHub repository header (top-right area), not inside this README text.
+If you prefer a direct link, open: **[Create from template](https://github.com/fatidaprilian/Agentic-Senior-Core/generate)**.
+Your new repository will instantly possess all the rules, configurations, and AI context files directly out of the box — zero CLI needed.
+
+### Option 0: NPM Install (Local or Global)
+
+If you already know you want the CLI from npm, use one of these paths:
+
+```bash
+npm exec --yes @ryuenn3123/agentic-senior-core init
+npm install -g @ryuenn3123/agentic-senior-core
+agentic-senior-core init
+```
+
+### Option 1: Interactive via GitHub Source (Pre-publish friendly)
+
+If npm package publication is not ready yet, run the CLI directly from GitHub and still keep the full interactive experience.
+
+```bash
+npm exec --yes --package=github:fatidaprilian/Agentic-Senior-Core agentic-senior-core init .
+```
+
+This gives the same interactive prompts to choose your profile (`beginner`, `balanced`, `strict`), stack, blueprint, and CI guardrails.
+
+If you want a plug-and-play starter instead of answering every question, use a preset:
+
+```bash
+npx @ryuenn3123/agentic-senior-core init --preset frontend-web
+npx @ryuenn3123/agentic-senior-core init --preset backend-api
+npx @ryuenn3123/agentic-senior-core init --preset mobile-react-native
+```
+
+### Option 2: GitHub Bootstrap Scripts (No npx required)
+
+Run directly from this repository bootstrap script and inject rules into your project root.
+
+Bootstrap script paths: `scripts/init-project.ps1` (Windows) and `scripts/init-project.sh` (Linux/macOS).
+
+Windows PowerShell:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\init-project.ps1 -TargetDirectory . -Profile balanced -Stack typescript -Blueprint api-nextjs -Ci true
+```
+
+Linux/macOS Bash:
+
+```bash
+bash ./scripts/init-project.sh . --profile balanced --stack typescript --blueprint api-nextjs --ci true
+```
+
+Both scripts clone Agentic-Senior-Core into a temporary directory, run the same CLI engine, then clean up automatically.
+
+If you want interactive selection, omit `-Profile`, `-Stack`, `-Blueprint`, and `-Ci` on the script command.
+
+### Option 3: Interactive Auto-Setup via npm/npx (Post-publish)
+
+If you have an existing project and want to infuse it with Staff-level context:
+
+```bash
+npx @ryuenn3123/agentic-senior-core init
+```
+
+Use team defaults (V2.0 track) with profile packs:
+
+```bash
+npx @ryuenn3123/agentic-senior-core init --profile-pack startup
+```
+
+The CLI is smart. It auto-detects your current development stack, helps you build a governance profile (select from `beginner`, `balanced`, or `strict`), and writes the compiled rules straight to your root automatically!
+
+If you are totally new to concepts like blueprints and guardrails, no problem — just run:
+```bash
+npx @ryuenn3123/agentic-senior-core init --newbie
+```
+
+### Skill Selector
+
+Use the unified skill selector to pick the right pack for a domain:
+
+```bash
+agentic-senior-core skill frontend --tier advance
+agentic-senior-core skill backend --tier expert
+agentic-senior-core skill fullstack --json
+```
+
+When you run `init`, the CLI now auto-activates the matching skill packs for the chosen stack and blueprint, so the compiled governance context includes the relevant frontend, backend, fullstack, and CLI guidance by default.
+
+### Token Optimization Mode (Enabled by Default on Init)
+
+Use this mode when your AI session is shell-heavy and context usage is high.
+By default, every `init` flow enables token optimization automatically (npx, npm exec, global CLI, preset, and interactive wizard).
+The optimization engine works in two modes:
+- Native fallback mode (no external dependency required)
+- External proxy mode (auto-detected when available)
+
+Quick start:
+
+```bash
+agentic-senior-core optimize . --agent copilot --enable
+agentic-senior-core optimize . --show
+agentic-senior-core optimize . --disable
+
+# Auto-enable during project initialization
+npx @ryuenn3123/agentic-senior-core init --token-optimize --token-agent copilot
+
+# Opt out when needed
+npx @ryuenn3123/agentic-senior-core init --no-token-optimize
+```
+
+When enabled, the CLI writes `.agent-context/state/token-optimization.json`, regenerates compiled rules, and adds compact command guidance to `.cursorrules` and `.windsurfrules`.
+If an external token proxy is available, the CLI prints setup hints. If not, native fallback guidance stays active, so outside users are not forced to install extra tooling.
+
+### Token Efficiency Benchmark Snapshot
+
+Latest local benchmark (2026-04-11) from `.agent-context/state/token-optimization-benchmark.json`:
+
+| Scenario | Baseline Token Estimate | Agentic Native Token Estimate | Native Savings | RTK Token Estimate | RTK Status |
+|----------|-------------------------|-------------------------------|----------------|--------------------|------------|
+| Latest commit detail review | 3798 | 177 | 95.34% | 3798 | Detected (`rtk` v0.35.0) |
+| Commit history review | 3730 | 889 | 76.17% | 1610 | Detected (`rtk` v0.35.0) |
+| Search result scan | 5339 | 1099 | 79.42% | 5339 | Detected (`rtk` v0.35.0) |
+| Average | - | - | 83.64% | 18.95% savings | Detected (`rtk` v0.35.0) |
+
+Method note:
+- Estimate formula is `ceil(output_chars / 4)`.
+- This is a command-output estimate, not provider-specific tokenizer output.
+- RTK results depend on host utilities. On Windows hosts without GNU `grep` or `ls`, RTK may fall back to `rtk git ...` paths for some scenarios.
+
+Reproduce and refresh this table:
+
+```bash
+npm run benchmark:token
+```
+
+### Install and Setup Choices
+
+The CLI now supports a smaller decision surface for first-time setup:
+
+| Path | Best for |
+|------|----------|
+| `agentic-senior-core launch` | Numbered interactive chooser for install and preset paths |
+| GitHub Template | Zero-install project bootstrap |
+| npm exec / npx | One-off setup on an existing repo |
+| npm install -g | Repeated local use from the shell |
+| `--preset` | Fast bootstrap with a curated stack and blueprint |
+| `optimize` | Optional token-aware shell output guidance with native fallback |
+
+### Supported Stack Map
+
+Use the stack that matches the project you are actually starting:
+
+| Stack | Recommended Blueprint | Best Fit |
+|-------|-----------------------|----------|
+| TypeScript | api-nextjs | Web app, fullstack product, CLI tooling |
+| Python | fastapi-service | API service, automation, data-heavy backend |
+| Go | go-service | Small, fast services and platform tooling |
+| Java | spring-boot-api | Enterprise APIs and service-oriented systems |
+| PHP | laravel-api | Conventional product backends |
+| C# | aspnet-api | Microsoft stack services and enterprise apps |
+| Rust | go-service | Performance-sensitive backend work |
+| Ruby | laravel-api | Mature product services and backend workflows |
+| React Native | mobile-app | Cross-platform mobile applications |
+| Flutter | mobile-app | Cross-platform mobile applications |
+
+### Benchmark Comparison (Current State)
+
+| Capability | antigravity-awesome-skills | awesome-copilot | MiniMax-AI/skills | Agentic-Senior-Core |
+|------------|----------------------------|-----------------|-------------------|---------------------|
+| Skill organization | Large curated library | Resource catalog + governance docs | Domain-focused packs | Unified folder-based domain packs with tier routing |
+| Architecture guidance | Strong practical patterns | Strong SoC and layered architecture | Strong applied templates | Consolidated architecture + domain enforcement |
+| CLI governance | Limited | Moderate | Moderate | Init/upgrade/output governance with dry-run and structured reports |
+| Distribution operations | Basic | Moderate | Strong release checklists | Publish, rollback, compatibility gates plus benchmark/sbom flows |
+| Review quality | Pattern-oriented | Checklist-oriented | Gate-oriented | Planning/security/benchmark review model with CI integration |
+
+### Option 4: Clone and Play
+Want to poke around under the hood? Just clone the repo and `npx @ryuenn3123/agentic-senior-core init` locally. No runtime dependencies needed — everything uses native Node.js!
+
+### Upgrade Existing Governance Packs (V1.x to V2.x)
+
+Yes, the upgrade flow still works. Use `--dry-run` first to preview changes, then apply with `--yes` when you are ready.
+
+Preview migration changes safely:
+
+```bash
+npx @ryuenn3123/agentic-senior-core upgrade --dry-run
+```
+
+Apply migration updates:
+
+```bash
+npx @ryuenn3123/agentic-senior-core upgrade --yes
+```
+
+---
+
+## Further Reading
+
+Our documentation has shifted into dedicated tracks to keep this README light:
+- **[FAQ / Concepts](docs/faq.md)**: Unfamiliar with Stacks, Blueprints, or Guardrails? Stalled on basic logic? Start here.
+- **[Deep Dive / Internals](docs/deep-dive.md)**: Explore the dynamic compiler, severity profiles, MCP integration, and granular LLM overrides here.
+- **[V2 Upgrade Playbook](docs/v2-upgrade-playbook.md)**: Benchmark-driven upgrade execution from antigravity-awesome-skills, awesome-copilot, and MiniMax skills.
+- **[Skill Platform](.agent-context/skills/README.md)**: Unified skill packs for frontend, backend, fullstack, CLI, distribution, and review quality with `advance` as the default tier.
+      The skill platform is now folder-based, so each domain has its own README and topic docs like a curated skills library.
+
+---
+
+## Core Capabilities
+
+- **Delivery Engine (CLI):** Interactive setup via GitHub source, bootstrap scripts, or `npx` after publish. Supported by a robust transactional installer with rollback protection.
+- **Verified Skill Marketplace:** Distribute and validate plugins securely with automated 4-dimension Trust Scoring and Evidence Bundles constraint validation.
+- **Dynamic Context Compiler:** Merges universal rules + selected stack + selected blueprint + optional CI guardrails into one dense, indexed rule file.
+- **Codebase Intelligence:** `.agent-context/state/` gives architecture/dependency boundaries so the agent understands high-risk areas.
+- **Override System:** `.agent-override.md` allows controlled enterprise exceptions without forking core rules.
+- **Automated Guardrails:** CI blueprints include LLM-as-a-Judge flow using `pr-checklist.md`.
+- **Pre-Publish Safety:** Built-in forbidden content checks detect hardcoded secrets and stray debugger artifacts before hitting the NPM registry.
+- **Machine-Readable CI Output:** LLM Judge emits `JSON_REPORT` payloads and writes `.agent-context/state/llm-judge-report.json` for PR/MR annotation tooling.
+- **MCP Self-Healing Loop:** `mcp.json` defines diagnostics + fix proposal workflow when lint/CI fails.
+
+---
+
+## Repository Structure
+
+```text
+.
+├── .cursorrules                    # Dynamic compiled governance entry point
+├── .windsurfrules                  # Dynamic compiled governance entry point
+├── .agent-override.md              # Team-specific exceptions (scoped + expiry)
+├── mcp.json                        # MCP self-healing workflow config
+├── AGENTS.md                       # Universal agent discovery
+├── .github/copilot-instructions.md # GitHub Copilot entry point
+├── .gemini/instructions.md         # Antigravity / Gemini entry point
+├── bin/
+│   └── agentic-senior-core.js      # Interactive CLI (Delivery Engine)
+├── .agent-context/
+│   ├── rules/                      # Universal engineering laws
+│   ├── stacks/                     # Language-specific profiles
+│   ├── blueprints/                 # Scaffolding and pipeline templates
+│   ├── review-checklists/          # AI self-audit guides
+│   ├── prompts/                    # Ready-to-use prompts
+│   └── state/                      # Architecture and dependency state maps
+│       ├── architecture-map.md
+│       └── dependency-map.md
+├── scripts/
+│   ├── validate.mjs                # Repository validator
+│   ├── llm-judge.mjs               # LLM-as-a-Judge CI gate
+│   ├── init-project.sh             # GitHub bootstrap script (Linux/macOS)
+│   └── init-project.ps1            # GitHub bootstrap script (Windows)
+├── docs/
+│   ├── faq.md
+│   └── deep-dive.md
+├── tests/
+│   ├── cli-smoke.test.mjs
+│   └── llm-judge.test.mjs
+├── package.json
+├── CONTRIBUTING.md
+├── LICENSE
+└── README.md
+```
+
+---
+
+## Validation
+
+Ensure everything is running smoothly before merging rules patches:
+
+```bash
+npm run validate
+```
+
+Track stack-detection KPI trends:
+
+```bash
+npm run benchmark:detection
+```
+
+---
+
+## Roadmap
+
+### Completed Milestones
+- V1.0 to V1.3: Core rules, multi-language stacks, advanced architecture patterns, and infrastructure blueprints.
+- V1.4: Dynamic Governance Engine (interactive CLI, context compiler, state maps, override system, guardrails, MCP self-healing).
+- V1.5: Newbie-First Experience (Node-first runtime, zero-install onboarding path, smart auto-detection, profile presets, LLM severity thresholds, docs split, smoke tests).
+
+### V1.6 (Released) — Enterprise Reliability and Team Workflow
+- Team profile packs and safer override governance shipped.
+- CI annotation standardization and stronger detection transparency shipped.
+- Upgrade assistant and benchmark coverage shipped.
+
+### V1.7 (Released) — Frontend Product Experience Governance Pack
+- Frontend usability checklist, execution playbook, and issue template shipped.
+- Frontend usability audit script and CI artifact workflow shipped.
+
+### V1.8 (Released) — Enterprise Release Operations and Compliance
+- Release-gate automation shipped with machine-readable artifact output.
+- CycloneDX SBOM generation and compliance artifact workflow shipped.
+- Operations playbook and release-operations checklist shipped.
+
+### Current Forward Plan
+- V2.0: Skill marketplace trust tiers, transactional installs, rollback safety, and launch-menu onboarding.
+- V2.5: Cross-model benchmark harness and anti-regression quality gates.
+- V3.0: Enterprise governance cloud, policy drift detection, and org-level override registry.
+
+Detailed timeline and success metrics: [docs/roadmap.md](docs/roadmap.md)
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution standards and workflow.
+
+---
+
+## License
+
+MIT — Use freely, enforce strictly.
+
+---
+
+<div align="center">
+
+**Stop letting AI write junior code.**
+**Give it the rules of a Staff Engineer.**
+
+</div>