@ryuenn3123/agentic-senior-core 4.3.15 → 5.1.0

package/CONTRIBUTING.md

@@ -1,93 +1,122 @@
 # Contributing to Agentic-Senior-Core
 
-Thanks for wanting to make AI agents write better code. Here's how to contribute.
+Thanks for wanting to make AI agents write better code.
 
 ---
 
 ## What You Can Contribute
 
-| Type | Where | Description |
-|------|-------|-------------|
-| New rule | `.agent-context/rules/` | Universal engineering standard |
-| Stack strategy update | `.agent-context/rules/`, `.agent-context/state/stack-research-snapshot.json` | Dynamic language/runtime guidance and evidence |
-| Structural planning guidance update | `.agent-context/prompts/`, `lib/cli/compiler.mjs` | Scope planning, docs bootstrap, and project-context guidance |
-| New checklist | `.agent-context/review-checklists/` | Self-audit guide |
-| State intelligence update | `.agent-context/state/` | Architecture boundaries and dependency map |
-| MCP workflow update | `mcp.json` | Self-healing automation flow |
+| Type | Where | Notes |
+|------|-------|-------|
+| Rule improvement | `AGENTS.md` | All rules live in one file |
+| New skill | `skills/<name>/SKILL.md` | Long-form workflow guidance |
+| New command | `commands/<name>.md` + `.toml` | Claude `.md`, Gemini `.toml` |
+| New host adapter | See adapter guide below | One file per host |
 | Bug fix | Any file | Typos, broken links, incorrect rules |
-| Improvement | Any file | Sharper wording, stricter boundaries |
 
 ---
 
 ## Content Quality Standard
 
-This is the single most important rule: **every file must be "galak" (strict/fierce).**
+Every rule must be opinionated, specific, and enforceable.
 
-Your contribution MUST be opinionated, specific, and enforceable. We reject generic advice, externally anchored rules, and borrowed-pattern guidance that can become accidental style anchors.
+### Litmus Test
 
-### The Litmus Test
 - Does your rule include concrete BANNED / REQUIRED boundaries?
-- Would an AI agent be able to enforce it without ambiguity?
+- Would an AI agent enforce it without ambiguity?
 - Does it teach the reader WHY, not just WHAT?
 
 If all three are "yes", it belongs here.
 
 ---
 
-## How to Add or Adjust Stack Strategy Signals (e.g., Python)
+## How to Edit Rules
 
-1. Update relevant universal guidance in `.agent-context/rules/` (typing, validation, architecture constraints).
-2. Add or adjust measurable stack evidence in `.agent-context/state/stack-research-snapshot.json`.
-3. Update stack-facing wording in prompts or CLI output when behavior changes.
-4. Run `npm run validate` to verify references and policy checks.
-5. Open a PR.
+All universal rules live in `AGENTS.md`. This is the single source of truth injected into every host via hooks.
+
+1. Edit `AGENTS.md`
+2. Run `npm test` to verify structure and size constraints
+3. Open a PR
+
+Keep `AGENTS.md` under 8KB (~1,200 tokens). Every byte is injected on every session start across all hosts. Concise rules with high signal-to-noise ratio.
 
 ---
 
-## How to Add or Adjust Structural Planning Guidance
+## How to Add a Skill
+
+Skills are long-form workflows that users invoke on demand (not always-on). They don't count against the always-on token budget.
 
-1. Update the planning guidance in `.agent-context/prompts/init-project.md` and related discovery guidance.
-2. Update compiler/init behavior if generated project-context guidance or bootstrap flow changes.
-3. Keep system boundaries, required docs, and validation boundaries explicit without silently recommending a framework from offline heuristics.
-4. Run `npm run validate` and `npm test`.
-5. Open a PR.
+1. Create `skills/<name>/SKILL.md` with frontmatter:
+   ```yaml
+   ---
+   name: asc-<name>
+   description: One-line description
+   ---
+   ```
+2. Create matching command files:
+   - `commands/<name>.md` (Claude Code format)
+   - `commands/<name>.toml` (Gemini format: `description` + `prompt` fields)
+3. If the skill should be available in OpenClaw, copy `SKILL.md` to `.openclaw/skills/<name>/SKILL.md`
+4. Run `npm test`
+5. Open a PR
 
 ---
 
-## How to Add a New Rule
+## How to Add a Host Adapter
+
+### Plugin-tier hosts (hooks + skills + commands)
+
+These hosts support full plugin systems. Create the host's manifest in its standard directory:
+
+| Host | Manifest path | Format |
+|------|--------------|--------|
+| Claude Code | `.claude-plugin/plugin.json` | JSON: name, version, skills, commands, hooks |
+| Codex CLI | `.codex-plugin/plugin.json` | JSON: name, skills, hooks, interface |
+| Copilot CLI | `.github/plugin/plugin.json` | JSON |
+| Devin | `.devin-plugin/plugin.json` | JSON minimal |
+| Hermes | `plugin.yaml` + `__init__.py` | YAML + Python |
+| OpenCode | `.opencode/plugins/agentic-senior-core.mjs` | JS module |
+
+### Instruction-tier hosts (single file copy)
+
+These hosts read a rules file from a standard path. The adapter file contains the full `AGENTS.md` content with host-specific frontmatter.
+
+| Host | Adapter path |
+|------|-------------|
+| Cursor | `.cursor/rules/agentic-senior-core.mdc` |
+| Windsurf | `.windsurf/rules/agentic-senior-core.md` |
+| Cline | `.clinerules/agentic-senior-core.md` |
+| Copilot (VS Code) | `.github/copilot-instructions.md` |
+| Kiro | `.kiro/steering/agentic-senior-core.md` |
 
-1. Create `.agent-context/rules/<rule-name>.md`
-2. Structure:
-   - Opening quote (sets the tone)
-   - Core principle (1-2 sentences)
-   - BANNED / REQUIRED sections with enforceable boundaries
-   - Decision tree or quick ruleset when it reduces ambiguity
-3. Update `AGENTS.md` or `.agent-context/` as the source, then verify thin adapters with `npm run check:adapters`
-4. Update `review-checklists/pr-checklist.md` when the rule is part of review scope
-5. Validate and PR
+After adding a new adapter:
+1. Add the file path to `package.json` `files` array
+2. Add the adapter to `lib/cli/commands/adapter.mjs` if it's instruction-tier
+3. Add a test assertion in `tests/adapter.test.mjs`
+4. Update `README.md` supported hosts table
+
+### Keeping adapter content aligned
+
+All instruction-tier adapter files must contain the same rule content as `AGENTS.md`. When you update `AGENTS.md`, update all adapter files. The test suite validates that all adapter files exist.
 
 ---
 
 ## 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**: `npm run validate` 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
+2. **Branch** from `main`: `feat/add-hermes-adapter` or `fix/security-rule-typo`
+3. **Write** your content following the quality standard
+4. **Test**: `npm test` must pass
+5. **Commit** with Conventional Commits: `feat(adapters): add hermes plugin`
+6. **Open PR** with what you changed and why
 
 ---
 
 ## What We Don't Accept
 
-- Generic content that reads like it was auto-generated without thought
+- Generic content that reads like auto-generated filler
 - Rules without concrete enforcement boundaries
-- Stack profiles for languages the author doesn't actually use in production
-- PRs that don't update the relevant source files, docs, validators, and checklists
+- PRs that don't update tests for structural changes
 
 ---
 
@@ -95,30 +124,31 @@ If all three are "yes", it belongs here.
 
 The npm package is published under `@ryuenn3123`, while the GitHub repository is hosted under `fatidaprilian`.
 
-### Architecture Boundaries
+### Architecture (v5.x)
 
-When contributing code to the CLI or the maintenance tools, respect the boundary between `lib/` and `scripts/`:
-
-- **`lib/`**: Contains the core CLI application logic. These files are executed by the package binary but are **never** copied into target user workspaces.
-- **`scripts/`**: Contains standalone tools (like validators, audits, and benchmarks) AND the MCP server (`scripts/mcp-server.mjs`). Code here must not depend on `lib/` because some scripts (like the MCP server) are copied directly to target workspaces where `lib/` does not exist.
+```
+AGENTS.md                    <-- single source of truth for rules
+hooks/session-start.js       <-- injects AGENTS.md on session start (CommonJS)
+hooks/subagent-start.js      <-- injects AGENTS.md into subagents (CommonJS)
+skills/*/SKILL.md            <-- on-demand workflow guidance
+commands/*.md                <-- Claude Code commands
+commands/*.toml              <-- Gemini CLI commands
+.claude-plugin/              <-- Claude Code plugin manifest
+.codex-plugin/               <-- Codex CLI plugin manifest
+.cursor/rules/               <-- Cursor adapter (instruction-tier)
+.windsurf/rules/             <-- Windsurf adapter
+lib/cli/commands/adapter.mjs <-- CLI adapter generator
+tests/adapter.test.mjs       <-- structure validation tests
+```
 
 ```bash
-# Clone
 git clone https://github.com/fatidaprilian/Agentic-Senior-Core.git
 cd Agentic-Senior-Core
-
-# Validate
-npm run validate
-
-# Clean ignored local reports/backups when the workspace gets noisy
-npm run clean:local
-
-# Test interactive CLI
-node ./bin/agentic-senior-core.js init /tmp/test-project
+npm test
 ```
 
 ---
 
 ## 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.
+Open an issue. Describe what you want to add and why.

package/README.md

@@ -2,13 +2,12 @@
 
 # Agentic-Senior-Core
 
-### Change your AI Agent to code like a Staff Engineer, not a Junior.
+### Universal AI coding rules. Write 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)
 
-**Production-grade Rules Engine for AI coding agents.**
-Works with Cursor, Windsurf, GitHub Copilot, Claude Code, Gemini, and other LLM-powered IDE workflows.
+**Install once. Works across all projects. Supports 16+ AI coding agents.**
 
 </div>
 
@@ -16,186 +15,236 @@ Works with Cursor, Windsurf, GitHub Copilot, Claude Code, Gemini, and other LLM-
 
 ## Install
 
+### Step 1: Install the package
+
 ```bash
-npx @ryuenn3123/agentic-senior-core init
+npm install -g @ryuenn3123/agentic-senior-core
 ```
 
-Initializes `AGENTS.md`, native import bridges, checklists, policies, state files, and the lazy `.agent-context/` rule library. Token optimization and Compact Natural Mode are enabled by default.
+### Step 2: Set up for your AI tool
 
-Options:
-- Add `--mcp-template` to generate VS Code MCP workspace config.
-- Default init keeps MCP files opt-in.
-- Add `--no-token-optimize` only when you do not want ASCX command guidance enabled.
-- Add `--local-only` to ignore instructions (AGENTS.md, .agent-context/, and bridges) in .gitignore so they are not pushed to GitHub.
-- Local backup snapshots are written under `.agentic-backup/` and excluded from version control.
+<details>
+<summary><b>Claude Code</b> (terminal agent)</summary>
 
-## Upgrade
+Rules load automatically via plugin hooks. No per-project files needed.
 
 ```bash
-npx @ryuenn3123/agentic-senior-core upgrade --dry-run
-npx @ryuenn3123/agentic-senior-core upgrade --yes
+claude plugin add fatidaprilian/Agentic-Senior-Core
 ```
 
-Preview changes with `--dry-run`, then apply with `--yes`. Upgrade prunes obsolete managed files by default; use `--no-prune` to keep them. User-owned files without Agentic markers are never overwritten.
+After install, every Claude Code session injects the rules on startup -- including subagents.
 
----
+</details>
 
-## Core Commands
+<details>
+<summary><b>Codex CLI</b> (terminal agent)</summary>
 
-> [!NOTE]
-> To run commands directly without `npx` (e.g., `ascx` or `agentic-senior-core`), install the CLI globally: `npm install -g @ryuenn3123/agentic-senior-core`.
+```bash
+codex plugins install agentic-senior-core
+```
 
-| Command | Purpose |
-|---------|---------|
-| `agentic-senior-core init` | Initialize the compact project guidance pack and native agent entrypoints |
-| `agentic-senior-core upgrade --dry-run` | Preview managed-surface upgrades |
-| `agentic-senior-core context "<request>" --json --file src/app/page.tsx` | Resolve request labels, rules, prompts, docs, file signals, budget status, and fallback status |
-| `ascx <command>` | Run a command through the local evidence-preserving output wrapper (safely falls back to passthrough if unsupported) |
-| `asc optimize status` | Check ASCX runtime token saver readiness |
-| `asc optimize doctor` | Diagnose ASCX availability, tee write safety, and compression conflicts |
-| `agentic-senior-core optimize --show` | Show token optimization state |
-| `agentic-senior-core mcp` | Start local MCP stdio runtime |
-| `npm run clean:local` | Remove ignored local reports, backups, benchmarks, and active-memory state |
+Rules load automatically via plugin hooks on every session.
 
-`ascx` dynamically compresses supported commands with noisy output (e.g., builds, tests, searches, and git logs). Other commands, pipes, redirects, and unsupported shell shapes safely pass through without compression. Compressed output includes a structured footer with command, exit code, filter name, estimated token reduction, and a raw tee path when safety requires it.
+</details>
 
-`asc` is a short alias for the main `agentic-senior-core` CLI. The doctor does not probe localhost services in this phase; `9router` status remains `not-checked`.
+<details>
+<summary><b>Gemini CLI</b> (terminal agent)</summary>
 
----
+Auto-detected. Gemini CLI reads `gemini-extension.json` from the installed package and loads `AGENTS.md` as context. Commands available as `.toml` format (`/asc-refactor`, `/asc-review`, `/asc-audit`).
 
-## What It Does
+</details>
 
-A coding agent that has read every framework tutorial still ships junior-grade work because nothing in its training tells it which trade-off matters in your codebase. This pack is a small set of plain-language rules an agent loads only when the work scope calls for them. The rules are written as invariants and bad habits to reject, not as opinions about which framework is fashionable. You install it with one command, revert with a backup, and it does not depend on any IDE or LLM provider.
+<details>
+<summary><b>Copilot CLI</b> (terminal agent)</summary>
 
-### How It Works
+Plugin files ship at `.github/plugin/`. After global npm install, register the plugin per your Copilot CLI version. Rules inject via hooks on every session.
 
-1. Agent reads `AGENTS.md` at the start of each session.
-2. `AGENTS.md` activates the default triad: Adaptive Context for scoped rule selection, ASCX wrappers for supported noisy commands, and Compact Natural Mode for final replies.
-3. For shell commands, the agent uses `ascx` wrappers that compress noisy output while preserving debugging evidence (exit codes, file paths, line numbers, root errors, truncation markers, and raw tee paths).
-4. For final replies, the agent applies `.agent-context/prompts/compact-natural-mode.md` so answers stay concise without losing commands, paths, errors, assumptions, validation status, risks, or next actions.
-5. Detailed rules live under `.agent-context/rules/` and load by scope: 21 rule files covering architecture, security, performance, testing, database, API, frontend, Docker, observability, resilience, migrations, background jobs, configuration, and versioning.
+</details>
 
-### Instruction Entrypoints
+<details>
+<summary><b>Cursor</b> (IDE)</summary>
 
-The canonical installed source is `AGENTS.md`.
+Run from your project root:
 
-Default init and upgrade keep the project root compact:
-- `AGENTS.md`
-- `CLAUDE.md`
-- `GEMINI.md`
-- `.agent-context/`
+```bash
+asc adapter --cursor
+```
 
-`CLAUDE.md` and `GEMINI.md` are native import bridges that load `AGENTS.md`. Detailed rules, prompts, checklists, policies, and state stay under `.agent-context/` and load by task scope.
+This copies one file to `.cursor/rules/agentic-senior-core.mdc`. Cursor reads it automatically on every session. Repeat per project.
 
-Deprecated legacy files (`.instructions.md`, `.agent-instructions.md`, `.cursorrules`, `.windsurfrules`, tool-specific rule directories) are no longer generated. Upgrade prunes Agentic-managed copies while preserving user-owned files.
+</details>
 
-### Long-Term Stability
+<details>
+<summary><b>Windsurf</b> (IDE)</summary>
 
-Rules are written as invariants, outcomes, and freshness criteria, not as named patterns, library prescriptions, or magic-number thresholds. Where a rule cites a specific tool or threshold, the citation block carries a freshness anchor so the next maintainer knows when the technology references were last validated.
+```bash
+asc adapter --windsurf
+```
 
----
+Copies one file to `.windsurf/rules/agentic-senior-core.md`. Repeat per project.
 
-## MCP Quick Setup (VS Code)
+</details>
 
-1. Generate workspace MCP config:
+<details>
+<summary><b>Cline</b> (VS Code extension)</summary>
 
 ```bash
-npx @ryuenn3123/agentic-senior-core init --mcp-template
+asc adapter --cline
 ```
 
-2. Open `MCP: Open Workspace Folder Configuration`.
-3. Confirm `.vscode/mcp.json` points to `node ./scripts/mcp-server.mjs` with `cwd: ${workspaceFolder}`.
-4. Trust and start the server in Chat Customizations > MCP Servers.
+Copies one file to `.clinerules/agentic-senior-core.md`. Repeat per project.
 
-Optional: enable `chat.mcp.autoStart` (Experimental) for auto-restart when MCP config changes.
+</details>
 
-If you see `Property $schema is not allowed`, keep `.vscode/mcp.json` without `$schema` and keep only `servers`.
+<details>
+<summary><b>GitHub Copilot</b> (VS Code extension)</summary>
 
----
+```bash
+asc adapter --copilot
+```
 
-## Design Direction
+Copies one file to `.github/copilot-instructions.md`. Repeat per project.
 
-For UI, UX, layout, screen, Tailwind, frontend, or redesign work, the pack routes agents through a compact design bootstrap before code changes. The flow asks the agent to reject generic defaults, choose a concrete interaction anchor, record creative commitments, and write the result into `docs/DESIGN.md`. Existing projects read the real repository and docs first; fresh projects ask the agent to recommend the stack from current evidence instead of hardcoding a framework.
+</details>
 
-See [docs/doc-index.md](docs/doc-index.md) for the full doc routing map.
+<details>
+<summary><b>Kiro</b> (IDE)</summary>
 
----
+```bash
+asc adapter --kiro
+```
+
+Copies one file to `.kiro/steering/agentic-senior-core.md`. Repeat per project.
+
+</details>
 
-## What's New
+<details>
+<summary><b>Devin / Hermes / OpenCode / OpenClaw / Antigravity</b></summary>
 
-### v4.2
+Plugin manifests ship in the npm package at their standard paths (`.devin-plugin/`, `plugin.yaml`, `.opencode/plugins/`, `.openclaw/skills/`, `.agents/`). After global npm install, each host auto-discovers or manually register per host docs.
 
-Adds `ascx` command wrapper to optimize token usage via high-signal adapters for `git status`, `git diff`, and `npm test` alongside the `Compact Natural Mode` response compression contract to reduce token overhead while retaining high-fidelity reasoning.
+</details>
 
-### v4.1
+<details>
+<summary><b>All IDE adapters at once</b></summary>
 
-Adds six backend rule files (`OBS-*`, `RES-*`, `MIG-*`, `JOB-*`, `CFG-*`, `VER-*`) and targeted refinements to `frontend-architecture.md`, `security.md`, `database-design.md`, and `api-docs.md`. See [CHANGELOG.md](CHANGELOG.md) for the full list.
+```bash
+asc adapter --all
+```
 
-### v4.0
+Generates adapter files for Cursor, Windsurf, Cline, Copilot, and Kiro in one go.
 
-Numbered Markdown rules with stable section IDs, bounded reflection, provider-free anti-halu benchmark, three-layer prompt caching contract, and per-integration caching scope enforcement. Caching numbers are scoped per integration; IDE wrapper integrations receive prefix stability without a measurable per-pack saving. See [docs/benchmark-reference.md](docs/benchmark-reference.md) for the reporting format and [CHANGELOG.md](CHANGELOG.md) for details.
+</details>
 
-Current package version: 4.3.3. Last published version: 4.3.2.
+**Terminal agents** (Claude Code, Codex, Gemini, Copilot CLI) = install once, always-on, zero per-project files.
+**IDE agents** (Cursor, Windsurf, Cline, Copilot VS Code, Kiro) = one file per project via `asc adapter`.
 
 ---
 
-## Validation
+## What It Does
 
-```bash
-npm run validate
-npm test
-npm run gate:release
-npm run benchmark:ascx
-```
+AI coding agents over-build by default. Ask for a date picker, the agent installs a library, writes a wrapper component, adds a stylesheet, and opens a timezone discussion.
+
+This plugin loads universal engineering rules on every session. Before writing any code, the agent runs a decision ladder:
+
+1. Does this need to be built at all?
+2. Does the codebase already have this?
+3. Does the stdlib or a native platform feature cover it?
+4. Does an already-installed dependency solve it?
+5. Can this be one straightforward function?
+6. Only then: write the minimum code that works.
+
+The rules also cover security, architecture, testing, error handling, API design, database safety, frontend accessibility, infrastructure, resilience, and async patterns. All universal invariants -- no project-specific configuration needed.
+
+### Not lazy about
+
+Input validation at trust boundaries, parameterized queries, auth checks, error handling that prevents data loss, accessibility, anything explicitly requested. These are never skipped.
+
+---
+
+## Supported Hosts
+
+| Host | Type | Install | Per-project files? |
+|------|------|---------|-------------------|
+| Claude Code | Terminal agent | `claude plugin add` | No |
+| Codex CLI | Terminal agent | `codex plugins install` | No |
+| Gemini CLI | Terminal agent | Auto-detected | No |
+| Copilot CLI | Terminal agent | Plugin registration | No |
+| Devin | Terminal agent | Auto-detected | No |
+| Hermes | Terminal agent | Plugin registration | No |
+| OpenCode | Terminal agent | Auto-detected | No |
+| OpenClaw | Terminal agent | Auto-detected | No |
+| Antigravity | Terminal agent | Auto-detected | No |
+| Cursor | IDE | `asc adapter --cursor` | Yes (1 file) |
+| Windsurf | IDE | `asc adapter --windsurf` | Yes (1 file) |
+| Cline | VS Code ext | `asc adapter --cline` | Yes (1 file) |
+| GitHub Copilot | VS Code ext | `asc adapter --copilot` | Yes (1 file) |
+| Kiro | IDE | `asc adapter --kiro` | Yes (1 file) |
 
 ---
 
-## Reference Docs
+## Commands
 
-- FAQ: docs/faq.md
-- Deep dive internals: docs/deep-dive.md
-- Deep analysis and roadmap: docs/deep-analysis-and-roadmap-backlog.md
-- Integration playbook: docs/integration-playbook.md
-- Benchmark and stack reference: docs/benchmark-reference.md
-- Project history: docs/archive/HISTORY.md
+Available on plugin hosts (Claude Code, Codex, Gemini CLI):
+
+| Command | Purpose |
+|---------|---------|
+| `/asc-refactor` | Structured refactoring workflow |
+| `/asc-review` | Production-risk code review with severity-ordered findings |
+| `/asc-audit` | Security and architecture audit |
+| `/asc-help` | Show available commands |
 
 ---
 
-## Release and npm Publish Flow
+## CLI
+
+```bash
+asc adapter [--cursor|--windsurf|--cline|--copilot|--kiro|--all]
+asc clean [--dry-run]
+asc status
+asc mcp
+asc --version
+asc --help
+```
 
-This repository publishes to npm through GitHub Actions on push to `main`.
+`ascx` is a token-saving command wrapper that compresses noisy output while preserving debugging evidence. Install globally and use as: `ascx git status`, `ascx npm test`.
 
-Release checklist:
+---
 
-1. Run `node scripts/bump-version.mjs <version>`.
-2. Fill the matching release notes in `CHANGELOG.md`.
-3. Run `npm run check:adapters`, `npm run validate`, `npm test`, `npm run gate:release`, and `git diff --check`.
-4. Commit with a Conventional Commit message.
-5. Push to `origin/main`.
+## Works With Other Plugins
 
-Package scope: `@ryuenn3123`. GitHub owner: `fatidaprilian`.
+ASC covers universal engineering standards (security, architecture, testing, API design, database safety). It is complementary to:
+
+- **ponytail** -- YAGNI minimalism and code reduction
+- **awesome-cursorrules** -- Framework-specific context and stack declarations
+
+Use them together. No conflicts.
 
 ---
 
-## Terminology Mapping (Final)
+## Migration from v4.x
 
-| Canonical Term | Developer-Facing Alias | Usage Rule |
-|----------------|------------------------|------------|
-| Federated Governance | Federated Rules Operations | Use canonical term in formal policy artifacts. |
-| Governance Engine | Rules Engine | Use alias in onboarding and day-to-day developer docs. |
-| Guardrails | Quality Checks | Use alias in implementation guidance and quickstart docs. |
+v5.0 is a breaking change. The per-project system (`.agent-context/`, bridge files, project scaffolding) is replaced by the universal plugin system.
 
-Rule: on first mention in developer-facing docs, include canonical term in parentheses.
+Clean up v4 artifacts from any project:
+```bash
+# Preview what will be removed
+asc clean --dry-run
 
-Examples:
-- `Federated Rules Operations (Federated Governance)`
-- `Rules Engine (Governance Engine)`
-- `quality checks (guardrails)`
+# Remove v4 files (.agent-context/, AGENTS.md, CLAUDE.md, GEMINI.md, etc.)
+asc clean
+```
 
-Compliance boundary: formal policy and audit artifacts must keep canonical terminology for operational traceability.
+This removes `.agent-context/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and other v4 bridge files from the current project directory. The global plugin replaces all of them.
 
 ---
 
-## License
+## Token Budget
+
+| Component | Tokens | When loaded |
+|-----------|--------|------------|
+| Rules (`AGENTS.md`) | ~1,200 | Every session + every subagent |
+| Each skill | ~500-800 | On user invocation only |
+| Commands | 0 | Metadata only |
 
-MIT - Use freely, enforce strictly.
+Total always-on cost: ~1,200 tokens per session.

package/__init__.py

@@ -0,0 +1,61 @@
+"""Hermes plugin for Agentic Senior Core."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parent
+SKILLS_DIR = ROOT / "skills"
+AGENTS_MD = ROOT / "AGENTS.md"
+
+SKILL_COMMANDS = {
+    "asc-refactor": "Structured refactoring workflow with pre-checks and validation.",
+    "asc-review": "Production-risk code review with severity-ordered findings.",
+    "asc-audit": "Security and architecture audit.",
+    "asc-help": "Show available ASC commands.",
+}
+
+
+def _read_agents_md() -> str:
+    try:
+        return AGENTS_MD.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def _pre_llm_call(**_: Any) -> dict[str, str] | None:
+    content = _read_agents_md()
+    return {"context": content} if content else None
+
+
+def _make_skill_handler(ctx: Any, command: str):
+    def handler(raw_args: str) -> str:
+        prompt = f"Load and follow the skill `asc:{command}`. {SKILL_COMMANDS[command]}"
+        if raw_args and raw_args.strip():
+            prompt += f"\n\nUser arguments: {raw_args.strip()}"
+        try:
+            if ctx.inject_message(prompt):
+                return f"Queued `{command}` for the agent."
+        except Exception:
+            pass
+        return prompt
+    return handler
+
+
+def register(ctx: Any) -> None:
+    for child in sorted(SKILLS_DIR.iterdir() if SKILLS_DIR.exists() else []):
+        skill_md = child / "SKILL.md"
+        if child.is_dir() and skill_md.exists():
+            ctx.register_skill(child.name, skill_md)
+
+    ctx.register_hook("pre_llm_call", _pre_llm_call)
+
+    for command, description in SKILL_COMMANDS.items():
+        ctx.register_command(
+            command,
+            _make_skill_handler(ctx, command),
+            description=description,
+            args_hint="[target or notes]",
+        )