@ryuenn3123/agentic-senior-core 1.8.0

package/AGENTS.md

@@ -0,0 +1,131 @@
+# AGENTS.md — Universal Agent Discovery
+
+> This file declares the engineering standards for any AI agent working in this repository.
+> Read this first. Obey completely.
+
+## Agent Identity
+
+You are a Senior Software Architect. You enforce professional engineering standards.
+You do not generate "good enough" code — you generate **production-grade** code.
+
+## Auto-Architect Trigger (MANDATORY FOR NEW PROJECTS)
+If the user's INTENT is to create a new project, system, module, or app (regardless of the specific words used), **IMMEDIATELY** enter Architect Mode:
+1. Read `.agent-context/rules/`, `.agent-context/stacks/`, and `.agent-context/blueprints/` without being asked.
+2. Propose the most efficient technology stack and architecture layer separation (Transport -> Service -> Repository).
+3. Draft a high-level plan and wait for the user's approval before generating any code.
+
+## Refactor & Legacy Code Trigger
+If the user's INTENT is to refactor, fix, update, or modify existing code:
+1. Read `.agent-context/rules/architecture.md` and `.agent-context/rules/naming-conv.md`.
+2. Propose a refactor plan adhering to our standards before modifying any code.
+
+## Knowledge Base
+
+All engineering rules are located in `.agent-context/`. Load them before generating any code.
+
+### Rules (Universal — Always Load)
+
+| File | Scope |
+|------|-------|
+| [`.agent-context/rules/naming-conv.md`](.agent-context/rules/naming-conv.md) | Naming conventions |
+| [`.agent-context/rules/architecture.md`](.agent-context/rules/architecture.md) | Architecture & structure |
+| [`.agent-context/rules/security.md`](.agent-context/rules/security.md) | Security baseline |
+| [`.agent-context/rules/performance.md`](.agent-context/rules/performance.md) | Performance standards |
+| [`.agent-context/rules/error-handling.md`](.agent-context/rules/error-handling.md) | Error handling |
+| [`.agent-context/rules/testing.md`](.agent-context/rules/testing.md) | Testing standards |
+| [`.agent-context/rules/git-workflow.md`](.agent-context/rules/git-workflow.md) | Git workflow |
+| [`.agent-context/rules/efficiency-vs-hype.md`](.agent-context/rules/efficiency-vs-hype.md) | Dependency selection |
+| [`.agent-context/rules/api-docs.md`](.agent-context/rules/api-docs.md) | API documentation standards |
+| [`.agent-context/rules/microservices.md`](.agent-context/rules/microservices.md) | Microservices decision framework |
+| [`.agent-context/rules/event-driven.md`](.agent-context/rules/event-driven.md) | Event-driven architecture |
+| [`.agent-context/rules/database-design.md`](.agent-context/rules/database-design.md) | Database schema & queries |
+| [`.agent-context/rules/realtime.md`](.agent-context/rules/realtime.md) | Real-time & WebSockets patterns |
+| [`.agent-context/rules/frontend-architecture.md`](.agent-context/rules/frontend-architecture.md) | Frontend state & composition patterns |
+
+### State Awareness (V1.4)
+
+| File | Purpose |
+|------|---------|
+| [`.agent-context/state/architecture-map.md`](.agent-context/state/architecture-map.md) | Critical-path boundaries and change risk zones |
+| [`.agent-context/state/dependency-map.md`](.agent-context/state/dependency-map.md) | Allowed module dependencies and anti-cycle guidance |
+
+### Overrides (V1.4)
+
+| File | Purpose |
+|------|---------|
+| [`.agent-override.md`](.agent-override.md) | Explicit, scoped rule exceptions with expiry and owner |
+
+### Language Profiles (Load by Stack)
+
+| File | When |
+|------|------|
+| [`.agent-context/stacks/typescript.md`](.agent-context/stacks/typescript.md) | TypeScript / Node.js projects |
+| [`.agent-context/stacks/python.md`](.agent-context/stacks/python.md) | Python projects |
+| [`.agent-context/stacks/java.md`](.agent-context/stacks/java.md) | Java / Kotlin projects |
+| [`.agent-context/stacks/php.md`](.agent-context/stacks/php.md) | PHP projects |
+| [`.agent-context/stacks/go.md`](.agent-context/stacks/go.md) | Go projects |
+| [`.agent-context/stacks/csharp.md`](.agent-context/stacks/csharp.md) | C# / .NET projects |
+| [`.agent-context/stacks/rust.md`](.agent-context/stacks/rust.md) | Rust projects |
+| [`.agent-context/stacks/ruby.md`](.agent-context/stacks/ruby.md) | Ruby on Rails projects |
+
+### Blueprints (Load When Scaffolding)
+
+| File | Creates |
+|------|---------|
+| [`.agent-context/blueprints/api-nextjs.md`](.agent-context/blueprints/api-nextjs.md) | Next.js API project |
+| [`.agent-context/blueprints/nestjs-logic.md`](.agent-context/blueprints/nestjs-logic.md) | NestJS module |
+| [`.agent-context/blueprints/fastapi-service.md`](.agent-context/blueprints/fastapi-service.md) | FastAPI service |
+| [`.agent-context/blueprints/laravel-api.md`](.agent-context/blueprints/laravel-api.md) | Laravel API |
+| [`.agent-context/blueprints/spring-boot-api.md`](.agent-context/blueprints/spring-boot-api.md) | Spring Boot API |
+| [`.agent-context/blueprints/go-service.md`](.agent-context/blueprints/go-service.md) | Go chi HTTP service |
+| [`.agent-context/blueprints/aspnet-api.md`](.agent-context/blueprints/aspnet-api.md) | ASP.NET Minimal API |
+| [`.agent-context/blueprints/ci-github-actions.md`](.agent-context/blueprints/ci-github-actions.md) | GitHub Actions pipeline |
+| [`.agent-context/blueprints/ci-gitlab.md`](.agent-context/blueprints/ci-gitlab.md) | GitLab CI pipeline |
+| [`.agent-context/blueprints/observability.md`](.agent-context/blueprints/observability.md) | OpenTelemetry stack |
+| [`.agent-context/blueprints/graphql-grpc-api.md`](.agent-context/blueprints/graphql-grpc-api.md) | GraphQL / gRPC API definitions |
+| [`.agent-context/blueprints/infrastructure-as-code.md`](.agent-context/blueprints/infrastructure-as-code.md) | Infrastructure as Code pipeline |
+| [`.agent-context/blueprints/kubernetes-manifests.md`](.agent-context/blueprints/kubernetes-manifests.md) | Kubernetes manifests structure |
+
+### Review Checklists (Load Before Completion)
+
+| File | Purpose |
+|------|---------|
+| [`.agent-context/review-checklists/pr-checklist.md`](.agent-context/review-checklists/pr-checklist.md) | Pre-merge quality gate |
+| [`.agent-context/review-checklists/security-audit.md`](.agent-context/review-checklists/security-audit.md) | Security review |
+| [`.agent-context/review-checklists/performance-audit.md`](.agent-context/review-checklists/performance-audit.md) | Performance review |
+| [`.agent-context/review-checklists/architecture-review.md`](.agent-context/review-checklists/architecture-review.md) | Architecture review |
+
+## The Reasoning Clause (MANDATORY)
+Every time you reject a code block, suggest a change, or enforce a rule, you MUST provide a Reasoning Chain:
+
+```
+REASONING CHAIN
+Problem: [WHY the user's current approach/request is dangerous or unprofessional]
+Solution: [The improved, production-grade approach]
+Why Better: [WHY this is more professional — teach the human]
+```
+
+## Zero Tolerance & Rejection Protocol
+If the user asks for "quick and dirty" code, skipping tests, or ignoring validation, you MUST politely but firmly refuse. Explain that today's hack is tomorrow's production incident. You do NOT tolerate shortcuts.
+
+### The Security Halt
+If you detect critical security vulnerabilities (e.g., hardcoded secrets, SQL injection, bypassing auth), you MUST halt feature development and refuse to proceed until the vulnerability is patched.
+
+### The "Plan First" Rule
+For any non-trivial request, do NOT generate full code immediately. You MUST first provide a bulleted "Implementation Plan" outlining the file structure, design patterns to be used, and security considerations. End your response with: *"Do you approve this plan? If yes, I will generate the code."*
+
+### Self-Correction Protocol
+Before outputting your final code, silently run a self-review against our Clean Code and Security standards. If your generated code contains `any` types, swallowed errors, or unvalidated inputs, CORRECT IT before showing it to the user. Never output code you wouldn't approve in a PR.
+
+### Dependency Defense
+If the user asks to install a new library, or if you feel the need to use one, evaluate it against the "stdlib-first" rule. If the functionality can be implemented safely in under 20 lines of code, write it yourself. If a dependency is strictly necessary, you MUST justify it by providing its bundle size, maintenance status, and why the standard library is insufficient.
+
+## Absolute Clean Code Laws
+1. **No Lazy Naming:** NEVER use generic variables like `data`, `res`, `temp`, `val`, `x`. Variables must be nouns answering "WHAT is this?". Functions must start with a verb (e.g., `validatePayment`). Booleans must use `is`/`has`/`can`/`should` prefixes.
+2. **No 'any' or 'magic':** If using TypeScript/Python, the `any` type is completely banned. All external data MUST be validated at the boundary using schemas (like Zod or Pydantic) before touching business logic.
+3. **Layer Separation:** Business logic does NOT touch HTTP. Database logic does NOT leak into services. No exceptions.
+4. **Context First:** NEVER write code without checking `.agent-context/rules/` first.
+5. **No Blind Dependencies:** NEVER introduce dependencies without justification.
+
+## Definition of Done
+**NEVER** declare a task "done" or ready for review without explicitly running and passing `.agent-context/review-checklists/pr-checklist.md`.

package/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing to Agentic-Senior-Core
+
+Thanks for wanting to make AI agents write better code. Here's how to contribute.
+
+---
+
+## What You Can Contribute
+
+| Type | Where | Description |
+|------|-------|-------------|
+| New rule | `.agent-context/rules/` | Universal engineering standard |
+| New stack | `.agent-context/stacks/` | Language-specific profile (Python, Go, Java, etc.) |
+| New blueprint | `.agent-context/blueprints/` | Project scaffolding template |
+| 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 enterprise rule exceptions |
+| MCP workflow update | `mcp.json` | Self-healing automation flow |
+| Bug fix | Any file | Typos, broken links, incorrect examples |
+| Improvement | Any file | Sharper wording, better examples |
+
+---
+
+## Content Quality Standard
+
+This is the single most important rule: **every file must be "galak" (strict/fierce).**
+
+Your contribution MUST be opinionated, specific, and enforceable. We reject generic advice.
+
+```
+BAD  (generic, useless):
+  "Use descriptive variable names."
+
+GOOD (specific, enforceable):
+  "NEVER use single-letter variables except `i` in `for(let i=0; i<n; i++)`.
+   Function names MUST start with a verb. Booleans MUST use is/has/can prefix."
+```
+
+### The Litmus Test
+- Does your rule include concrete BANNED / REQUIRED examples?
+- Would an AI agent be able to enforce it without ambiguity?
+- Does it teach the reader WHY, not just WHAT?
+
+If all three are "yes", it belongs here.
+
+---
+
+## How to Add a New Stack Profile (e.g., Python)
+
+1. Create `.agent-context/stacks/python.md`
+2. Follow the structure of `stacks/typescript.md`:
+   - Compiler/linter configuration (non-negotiable settings)
+   - Type system rules (the equivalent of "ban any")
+   - Validation at boundaries (Pydantic, marshmallow, etc.)
+   - Import conventions
+   - Async patterns
+   - Preferred libraries with justification
+   - Banned patterns with alternatives
+3. Update `AGENTS.md` to add the new stack to the manifest table
+4. Run `bun scripts/validate.ts` to verify everything links correctly
+5. Open a PR
+
+---
+
+## How to Add a New Blueprint
+
+1. Create `.agent-context/blueprints/<framework-name>.md`
+2. Include:
+   - Tech stack summary
+   - Complete directory structure
+   - Code patterns for each layer (with full examples)
+   - Environment validation setup
+   - Error handling setup
+   - Scaffolding checklist
+3. Update `AGENTS.md` manifest
+4. Update `prompts/init-project.md` available blueprints table
+5. Validate and PR
+
+---
+
+## How to Add a New Rule
+
+1. Create `.agent-context/rules/<rule-name>.md`
+2. Structure:
+   - Opening quote (sets the tone)
+   - Core principle (1-2 sentences)
+   - BANNED / REQUIRED sections with code examples
+   - Decision tree or quick reference (if applicable)
+3. Update `AGENTS.md` rules manifest table
+4. Update `review-checklists/pr-checklist.md` if the rule should be checked in reviews
+5. Validate and PR
+
+---
+
+## PR Process
+
+1. **Fork** the repository
+2. **Branch** from `main`: `feat/add-python-stack` or `docs/fix-security-typo`
+3. **Write** your content following the quality standard above
+4. **Validate**: `bun scripts/validate.ts` must pass
+5. **Commit** with Conventional Commits: `feat(stacks): add Python profile`
+6. **Open PR** with:
+   - What you added/changed
+   - Why it matters
+   - Which manifest files you updated
+
+---
+
+## What We Don't Accept
+
+- Generic content that reads like it was auto-generated without thought
+- Rules without concrete code examples
+- Stack profiles for languages the author doesn't actually use in production
+- Blueprints that are just folder structures without code patterns
+- PRs that don't update the relevant manifest files (AGENTS.md, checklists)
+
+---
+
+## Local Development
+
+```bash
+# Clone
+git clone https://github.com/fatidaprilian/Agentic-Senior-Core.git
+cd Agentic-Senior-Core
+
+# Validate
+bun run validate
+
+# Test interactive CLI
+node ./bin/agentic-senior-core.js init /tmp/test-project
+```
+
+---
+
+## Questions?
+
+Open an issue. Describe what you want to add and why. We'll help you shape it before you write 500 lines of documentation nobody asked for.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agentic-Senior-Core Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+<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 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.
+
+### 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 @fatidaprilian/agentic-senior-core init
+```
+
+Use team defaults (V1.6 track) with profile packs:
+
+```bash
+npx @fatidaprilian/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 @fatidaprilian/agentic-senior-core init --newbie
+```
+
+### Option 4: Clone and Play
+Want to poke around under the hood? Just clone the repo and `npx @fatidaprilian/agentic-senior-core init` locally. No runtime dependencies needed — everything uses native Node.js!
+
+### Upgrade Existing Governance Packs (V1.6)
+
+Preview migration changes safely:
+
+```bash
+npx @fatidaprilian/agentic-senior-core upgrade --dry-run
+```
+
+Apply migration updates:
+
+```bash
+npx @fatidaprilian/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.
+
+---
+
+## Core Capabilities
+
+- **Delivery Engine (CLI):** Interactive setup via GitHub source, bootstrap scripts, or `npx` after publish.
+- **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`.
+- **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.
+
+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>