@ryuenn3123/agentic-senior-core 5.4.0 → 5.6.0

package/README.md

@@ -28,8 +28,18 @@ npm install -g @ryuenn3123/agentic-senior-core
 
 Rules load automatically via plugin hooks. No per-project files needed.
 
+From inside Claude Code, add the marketplace then install:
+
+```
+/plugin marketplace add fatidaprilian/Agentic-Senior-Core
+/plugin install agentic-senior-core@agentic-senior-core
+```
+
+Or from your terminal shell:
+
 ```bash
-claude plugin add fatidaprilian/Agentic-Senior-Core
+claude plugin marketplace add fatidaprilian/Agentic-Senior-Core
+claude plugin install agentic-senior-core@agentic-senior-core
 ```
 
 After install, every Claude Code session injects the rules on startup -- including subagents.
@@ -220,8 +230,13 @@ Antigravity IDE reads it automatically with `trigger: always_on`.
 Copy the plugin bundle to Antigravity's global plugin directory:
 
 ```powershell
-# Windows
-xcopy /E /I "%APPDATA%\npm\node_modules\@ryuenn3123\agentic-senior-core\.agents\plugins\agentic-senior-core" "%USERPROFILE%\.gemini\config\plugins\agentic-senior-core"
+# Windows (PowerShell)
+Copy-Item -Recurse -Force "$env:APPDATA\npm\node_modules\@ryuenn3123\agentic-senior-core\.agents\plugins\agentic-senior-core" "$env:USERPROFILE\.gemini\config\plugins\agentic-senior-core"
+```
+
+```cmd
+:: Windows (cmd.exe)
+xcopy /E /I /Y "%APPDATA%\npm\node_modules\@ryuenn3123\agentic-senior-core\.agents\plugins\agentic-senior-core" "%USERPROFILE%\.gemini\config\plugins\agentic-senior-core"
 ```
 
 ```bash
@@ -229,7 +244,9 @@ xcopy /E /I "%APPDATA%\npm\node_modules\@ryuenn3123\agentic-senior-core\.agents\
 cp -r "$(npm root -g)/@ryuenn3123/agentic-senior-core/.agents/plugins/agentic-senior-core" ~/.gemini/config/plugins/
 ```
 
-The plugin bundle includes rules, skills (`/asc-review`, `/asc-audit`, `/asc-refactor`), and `plugin.json`.
+The plugin bundle includes rules, skills (`/asc-review`, `/asc-audit`, `/asc-refactor`, `/asc-reference`, `/asc-debt`), and `plugin.json`.
+
+> Note: `npm update -g` refreshes the npm package only. The global plugin copy does not auto-update -- re-run the copy command above after each update.
 
 </details>
 
@@ -302,7 +319,7 @@ Input validation at trust boundaries, parameterized queries, auth checks, error
 
 | Host | Type | Install | Per-project files? |
 |------|------|---------|-------------------|
-| Claude Code | Terminal agent | `claude plugin add` | No |
+| Claude Code | Terminal agent | `/plugin install` | No |
 | Codex CLI | Terminal agent | `codex plugins install` | No |
 | Gemini CLI | Terminal agent | Auto-detected | No |
 | Copilot CLI | Terminal agent | Plugin registration | No |
@@ -336,6 +353,8 @@ Available on plugin hosts (Claude Code, Codex, Gemini CLI):
 | `/asc-refactor` | Structured refactoring workflow |
 | `/asc-review` | Production-risk code review with severity-ordered findings |
 | `/asc-audit` | Security and architecture audit |
+| `/asc-reference` | Domain-specific rules (testing, API, database, frontend, infra, resilience) |
+| `/asc-debt` | Track deferred enforcement violations (add, list, resolve, summary) |
 | `/asc-help` | Show available commands |
 
 ---
@@ -367,6 +386,26 @@ Use them together. No conflicts.
 
 ---
 
+## Benchmarks
+
+Measured on `claude-opus-4-6` using headless Claude Code sessions against real tasks.
+
+| | LOC | Tokens | Cost | Duration | Safety |
+|---|---|---|---|---|---|
+| **Simple tasks** | 0% | -3% to -8% | -1% | -2% to -13% | 100% |
+| **Complex tasks** | **-18%** | **-30%** | **-42%** | **-18%** | 100% |
+
+On complex, ambiguous tasks (auth systems, insecure CRUD refactors) — where over-engineering typically occurs — ASC produces **18% less code**, uses **30% fewer tokens**, costs **42% less**, and finishes **18% faster**.
+
+On trivial tasks the model is already concise, so gains are marginal.
+
+Full methodology and raw data: [`benchmarks/RESULTS.md`](benchmarks/RESULTS.md)
+
+> Model: `claude-opus-4-6` · n=1-2 per task · Baseline = Claude without rules (not zero-prompt).
+> Opus is inherently disciplined — gains on more verbose models would likely be larger.
+
+---
+
 ## Migration from v4.x
 
 v5.0 is a breaking change. The per-project system (`.agent-context/`, bridge files, project scaffolding) is replaced by the universal plugin system.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-senior-core",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "description": "Universal AI coding rules. Write code like a staff engineer.",
   "author": "fatidaprilian",
   "license": "MIT",

package/hooks/copilot-hooks.json

@@ -16,6 +16,15 @@
         "powershell": "node \"${PLUGIN_ROOT}\\hooks\\subagent-start.js\"",
         "timeoutSec": 5
       }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "matcher": "Edit|Write",
+        "bash": "node \"${PLUGIN_ROOT}/hooks/post-edit-enforce.js\"",
+        "powershell": "node \"${PLUGIN_ROOT}\\hooks\\post-edit-enforce.js\"",
+        "timeoutSec": 5
+      }
     ]
   }
 }

package/hooks/hooks.json

@@ -26,6 +26,20 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-enforce.js\"; exit 0",
+            "commandWindows": "if (Get-Command node -ErrorAction SilentlyContinue) { node \"$env:CLAUDE_PLUGIN_ROOT\\hooks\\post-edit-enforce.js\" }",
+            "timeout": 5,
+            "statusMessage": "ASC ladder check..."
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/post-edit-enforce.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// Agentic Senior Core — PostToolUse enforcement hook
+// Fires after Edit/Write. Checks for ladder violations and injects a nudge.
+// Supports Claude Code, Codex CLI, and GitHub Copilot CLI.
+
+const path = require('path');
+
+const STDLIB_DUPLICATES = new Set([
+  'lodash', 'lodash-es', 'underscore',
+  'moment', 'dayjs',
+  'uuid', 'nanoid',
+  'chalk', 'kleur', 'colorette',
+  'axios', 'got', 'node-fetch', 'superagent',
+  'mkdirp', 'rimraf', 'del',
+  'glob', 'globby',
+  'left-pad', 'pad-left',
+  'is-odd', 'is-even', 'is-number', 'is-string',
+  'path-exists', 'fs-extra',
+]);
+
+const SOURCE_EXTENSIONS = new Set([
+  'js', 'ts', 'mjs', 'cjs', 'jsx', 'tsx',
+  'py', 'rb', 'go', 'rs', 'java', 'kt', 'swift', 'cs',
+]);
+
+const LOC_DELTA_THRESHOLD = 30;
+const NEW_FILE_LINE_THRESHOLD = 50;
+
+let inputBuffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', function (chunk) { inputBuffer += chunk; });
+process.stdin.on('end', function () {
+  try {
+    const data = JSON.parse(inputBuffer);
+    const toolName = data.tool_name || '';
+    const toolInput = data.tool_input || {};
+    const filePath = toolInput.file_path || '';
+    const findings = [];
+
+    if (filePath.endsWith('package.json') || filePath.endsWith('package.json5')) {
+      checkDependencyAddition(toolName, toolInput, findings);
+    }
+
+    const ext = path.extname(filePath).slice(1);
+    if (SOURCE_EXTENSIONS.has(ext)) {
+      if (toolName === 'Edit') {
+        checkLocDelta(toolInput, filePath, findings);
+      } else if (toolName === 'Write') {
+        checkNewFileSize(toolInput, filePath, findings);
+      }
+    }
+
+    if (findings.length === 0) return;
+
+    const nudge = '[ASC enforcement] ' + findings.join(' ') + ' Review the decision ladder before continuing.';
+    emit(nudge);
+  } catch (_) {
+    // Silent fail — enforcement must not break the session
+  }
+});
+
+function checkDependencyAddition(toolName, toolInput, findings) {
+  var target = toolName === 'Edit' ? (toolInput.new_string || '') : (toolInput.content || '');
+  var baseline = toolName === 'Edit' ? (toolInput.old_string || '') : '';
+
+  var depPattern = /"([^"]+)"\s*:\s*"[~^>=<*]?\d/g;
+  var newDeps = extractDeps(target, depPattern);
+  var oldDeps = extractDeps(baseline, depPattern);
+
+  var added = newDeps.filter(function (d) { return oldDeps.indexOf(d) === -1; });
+  if (added.length === 0) return;
+
+  var stdlibDupes = added.filter(function (d) { return STDLIB_DUPLICATES.has(d); });
+  if (stdlibDupes.length > 0) {
+    findings.push(
+      'Dependency ' + stdlibDupes.join(', ') + ' may duplicate stdlib/platform features. '
+      + 'Ladder step 3: does the standard library cover this?'
+    );
+  } else {
+    findings.push(
+      'New dependency added: ' + added.join(', ') + '. '
+      + 'Ladder step 3-4: stdlib or already-installed alternative?'
+    );
+  }
+}
+
+function extractDeps(text, pattern) {
+  var matches = [];
+  var match;
+  while ((match = pattern.exec(text)) !== null) {
+    matches.push(match[1]);
+  }
+  return matches;
+}
+
+function checkLocDelta(toolInput, filePath, findings) {
+  var newLines = (toolInput.new_string || '').split('\n').length;
+  var oldLines = (toolInput.old_string || '').split('\n').length;
+  var delta = newLines - oldLines;
+  if (delta > LOC_DELTA_THRESHOLD) {
+    findings.push(
+      'Edit added ' + delta + ' net lines to ' + path.basename(filePath) + '. '
+      + 'Ladder step 5: can this be one straightforward function?'
+    );
+  }
+}
+
+function checkNewFileSize(toolInput, filePath, findings) {
+  var lines = (toolInput.content || '').split('\n').length;
+  if (lines > NEW_FILE_LINE_THRESHOLD) {
+    findings.push(
+      'New file ' + path.basename(filePath) + ' created with ' + lines + ' lines. '
+      + 'Ladder step 1-2: does this need to be built? Does the codebase already have this?'
+    );
+  }
+}
+
+function emit(nudge) {
+  try {
+    var isCopilot = Boolean(process.env.COPILOT_PLUGIN_DATA);
+    var output = {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: nudge,
+      },
+    };
+    if (isCopilot) {
+      output = { additionalContext: nudge };
+    }
+    process.stdout.write(JSON.stringify(output));
+  } catch (_) {
+    // EPIPE — silent
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "5.4.0",
+  "version": "5.6.0",
   "type": "module",
   "description": "Universal AI coding rules. Write code like a staff engineer, not a junior.",
   "bin": {

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: agentic-senior-core
-version: 5.1.0
+version: 5.6.0
 description: Universal AI coding rules. Write code like a staff engineer.
 author: fatidaprilian
 provides_hooks:
@@ -14,3 +14,5 @@ provides_skills:
   - asc-refactor
   - asc-review
   - asc-audit
+  - asc-debt
+  - asc-reference

package/scripts/mcp-server/constants.mjs

@@ -37,17 +37,10 @@ function resolvePackageVersion() {
 export const PACKAGE_VERSION = resolvePackageVersion();
 
 export const TEST_SUITE_ARGS = {
-  full: ['--test', './tests/cli-smoke.test.mjs', './tests/mcp-server.test.mjs', './tests/llm-judge.test.mjs', './tests/operations.test.mjs'],
-  cli: ['--test', './tests/cli-smoke.test.mjs'],
-  operations: ['--test', './tests/operations.test.mjs'],
-  'llm-judge': ['--test', './tests/llm-judge.test.mjs'],
+  adapter: ['--test', './tests/adapter.test.mjs'],
 };
 
-export const INTERNAL_SCRIPT_PATHS = {
-  validate: resolve(REPOSITORY_ROOT, 'scripts', 'validate.mjs'),
-  release_gate: resolve(REPOSITORY_ROOT, 'scripts', 'release-gate.mjs'),
-  forbidden_content_check: resolve(REPOSITORY_ROOT, 'scripts', 'forbidden-content-check.mjs'),
-};
+export const INTERNAL_SCRIPT_PATHS = {};
 
 function getAvailableTestSuites() {
   return Object.entries(TEST_SUITE_ARGS)

package/skills/asc/SKILL.md

@@ -7,8 +7,19 @@ Universal AI coding rules. Write code like a staff engineer.
 - `/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-reference` -- Domain-specific rules (testing, API, database, frontend, infra, resilience)
+- `/asc-debt` -- Track deferred enforcement violations (add, list, resolve, summary)
 - `/asc-help` -- Show this help
 
+## Enforcement
+
+On plugin-tier hosts (Claude Code, Codex CLI, Copilot CLI), a PostToolUse hook fires after every Edit/Write and checks:
+- New dependencies against stdlib duplicates (decision ladder step 3)
+- LOC delta > 30 lines on edits (step 5)
+- New files > 50 lines (steps 1–2)
+
+Violations inject a nudge referencing the specific ladder step. The hook is silent when no issues are found.
+
 ## What It Does
 
 Loads universal engineering rules on every session: code quality, architecture, security, error handling, testing, API design, database, frontend, infrastructure, resilience, and async patterns.

package/skills/asc-debt/SKILL.md

@@ -0,0 +1,64 @@
+# Debt Ledger
+
+Track deferred enforcement violations. When an ASC ladder nudge fires and the shortcut is accepted rather than fixed, log it here for later resolution.
+
+## Storage
+
+Entries persist in `.agent-context/state/debt-ledger.json` via MCP `state_read`/`state_write`. The ledger is a JSON array of entry objects.
+
+## Entry Format
+
+```json
+{
+  "id": "sequential integer",
+  "file": "path/to/file.ts",
+  "ladderStep": "3",
+  "violation": "Added axios — stdlib fetch covers this",
+  "addedAt": "ISO-8601 timestamp",
+  "status": "open | resolved",
+  "resolvedAt": "ISO-8601 timestamp or null"
+}
+```
+
+## Operations
+
+### Add Entry
+
+When an enforcement nudge fires and the violation is deferred:
+
+1. Read the current ledger via `state_read` (path: `debt-ledger.json`). If missing, start with `[]`.
+2. Append a new entry with the next sequential `id`, the file path, ladder step, and a one-line violation summary.
+3. Write the updated ledger via `state_write` (path: `debt-ledger.json`, mode: `overwrite`).
+4. Confirm: "Logged to debt ledger: [violation summary]"
+
+### List Open Debt
+
+1. Read the ledger via `state_read`.
+2. Filter to entries where `status` is `"open"`.
+3. Display as a table: ID, file, ladder step, violation, age.
+4. If no open entries, say so explicitly.
+
+### Resolve Entry
+
+When a deferred violation has been addressed:
+
+1. Read the ledger.
+2. Set the matching entry's `status` to `"resolved"` and `resolvedAt` to the current timestamp.
+3. Write the updated ledger.
+4. Confirm: "Resolved debt #[id]: [violation summary]"
+
+### Summary
+
+1. Read the ledger.
+2. Report: total entries, open count, resolved count, oldest open entry age.
+
+## When to Log
+
+Log a debt entry when ALL of these are true:
+- The PostToolUse enforcement hook fired a nudge
+- The agent acknowledged the nudge but proceeded without fixing the violation
+- The violation is deferrable (not a security issue — security violations must be fixed immediately)
+
+## Integration
+
+The `/asc` skill documents the enforcement loop. This ledger captures what enforcement flags but the session defers. Use `/asc-debt` at session end or before commits to review outstanding shortcuts.

package/skills/asc-refactor/SKILL.md

@@ -14,7 +14,7 @@ Structured refactoring workflow. Preserves existing behavior while improving str
 - Improve clarity, boundaries, naming, validation, error handling, and tests.
 - Prioritize maintainability over compressed one-liners.
 - Keep the main flow traceable. Use early returns where they reduce nesting.
-- Do not introduce abstractions before the repeated pattern is real.
+- Introduce abstractions only when the repeated pattern is real and visible.
 - Split large files when the split makes the flow easier to understand.
 - Remove code that does not carry behavior, safety, clarity, maintainability, or test value.
 - Prefer the shorter implementation only when it keeps the same guarantees.

package/skills/asc-reference/SKILL.md

@@ -0,0 +1,51 @@
+# ASC Domain Reference
+
+Domain-specific coding rules for testing, API design, database queries, frontend components, infrastructure configs, and service resilience. Load this skill when working on any of these domains.
+
+## Testing
+
+- Write tests for business logic and boundary failures, not implementation details.
+- Cover happy path, error paths, edge cases, and empty states.
+- Tests must be fast, isolated, deterministic.
+- Integration tests for critical data paths.
+- Sensitive mutations need idempotency or duplicate-submit coverage.
+- CI pipelines block on test failures.
+
+## API Design
+
+- Consistent resource naming and HTTP semantics.
+- Bounded list reads: always paginate or set explicit limits.
+- Idempotent for side-effect mutations. Document retry behavior.
+- Backward-compatible by default. Version breaking changes explicitly.
+- Sync docs in the same commit when changing API, CLI, or schema.
+
+## Database
+
+- Use eager loading or batching to eliminate N+1 queries.
+- Paginate all growable datasets. No unbounded queries.
+- Multi-table mutations run inside transactions.
+- Monetary amounts: integer minor units or exact decimal. Never floats.
+- Timestamps in UTC. No naive timestamps.
+- Schema changes require versioned, reversible migrations.
+- Never modify merged migrations. Create new ones.
+
+## Frontend
+
+- Semantic HTML before custom components.
+- WCAG 2.2 AA is the accessibility floor.
+- Responsive by default. Handle empty, loading, error, and offline states.
+- No placeholder, lorem, or TODO content in production UI.
+
+## Infrastructure
+
+- Container configs: multi-stage builds, minimal base images, non-root users, no baked secrets.
+- Configuration from environment, validated at startup. Fail fast if invalid.
+- Structured logging with correlation IDs. No PII in logs.
+
+## Resilience
+
+- Every outbound network call has a strict timeout.
+- Retries use exponential backoff with jitter and max attempt limits.
+- Only retry idempotent operations.
+- Circuit breakers for unhealthy dependencies.
+- Graceful degradation on non-critical dependency failure.

package/skills/asc-review/SKILL.md

@@ -7,6 +7,7 @@ Production-risk code review. Prioritize findings by severity.
 1. Read the changed files and understand the scope.
 2. For UI changes, check accessibility and design consistency.
 3. For API changes, check contract stability and documentation sync.
+4. Walk the decision ladder for each new file or dependency: does this need to exist, could the stdlib or an existing dependency handle it?
 
 ## Finding Priority Order
 
@@ -33,11 +34,11 @@ Production-risk code review. Prioritize findings by severity.
 - External input validated at trust boundaries.
 - Secrets, tokens, credentials not committed or logged.
 - Authorization enforced at a trusted boundary.
-- Error responses do not leak internals.
+- Error responses keep internal details out of client responses.
 
 ### Architecture
-- Layer boundaries clear. Controllers do not hold business logic.
-- No premature abstraction. No clever hacks.
+- Layer boundaries clear. Controllers handle protocol translation only; business logic stays in services.
+- Abstractions backed by real duplication, not prediction. Straightforward code over clever solutions.
 - Complexity budget applied: fewer moving parts without losing safety.
 
 ### Testing