@ryuenn3123/agentic-senior-core 5.6.0 → 5.8.0

package/lib/cli/commands/global.mjs

@@ -0,0 +1,196 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDirectoryPath = path.dirname(currentFilePath);
+const REPOSITORY_ROOT = path.resolve(currentDirectoryPath, '..', '..', '..');
+const HOME = os.homedir();
+
+const ASC_MARKER = '# Agentic Senior Core';
+
+function vscodeUserPromptsDirectory() {
+  if (process.platform === 'win32') {
+    return path.join(process.env.APPDATA ?? path.join(HOME, 'AppData', 'Roaming'), 'Code', 'User', 'prompts');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(HOME, 'Library', 'Application Support', 'Code', 'User', 'prompts');
+  }
+  return path.join(HOME, '.config', 'Code', 'User', 'prompts');
+}
+
+const GLOBAL_TARGETS = {
+  antigravity: {
+    label: 'Google Antigravity IDE',
+    kind: 'directory',
+    sourcePath: '.agents/plugins/agentic-senior-core',
+    targetPath: () => path.join(HOME, '.gemini', 'config', 'plugins', 'agentic-senior-core'),
+    note: 'Full plugin bundle (rules + skills), always-on in every project.',
+  },
+  cline: {
+    label: 'Cline',
+    kind: 'file',
+    sourcePath: '.clinerules/agentic-senior-core.md',
+    targetPath: () => path.join(HOME, 'Documents', 'Cline', 'Rules', 'agentic-senior-core.md'),
+    note: 'Toggleable in the Cline rules panel.',
+  },
+  roo: {
+    label: 'Roo Code',
+    kind: 'file',
+    sourcePath: '.roo/rules/agentic-senior-core.md',
+    targetPath: () => path.join(HOME, '.roo', 'rules', 'agentic-senior-core.md'),
+    note: 'Roo Code was discontinued in May 2026; kept for existing installs.',
+  },
+  kilocode: {
+    label: 'Kilo Code',
+    kind: 'file',
+    sourcePath: '.kilocode/rules/agentic-senior-core.md',
+    targetPath: () => path.join(HOME, '.kilocode', 'rules', 'agentic-senior-core.md'),
+    note: 'Kilo v7+: prefer adding the file path to the instructions array in ~/.config/kilo/kilo.jsonc (auto-updates with npm).',
+  },
+  kiro: {
+    label: 'Kiro',
+    kind: 'file',
+    sourcePath: '.kiro/steering/agentic-senior-core.md',
+    targetPath: () => path.join(HOME, '.kiro', 'steering', 'agentic-senior-core.md'),
+    note: 'Global steering has known loading bugs in some Kiro builds; fall back to asc adapter --kiro if rules are not picked up.',
+  },
+  openhands: {
+    label: 'OpenHands',
+    kind: 'file',
+    sourcePath: '.openhands/microagents/agentic-senior-core.md',
+    targetPath: () => path.join(HOME, '.openhands', 'microagents', 'agentic-senior-core.md'),
+    note: 'Works in CLI/headless/dev modes. Docker runs need the directory mounted.',
+  },
+  windsurf: {
+    label: 'Windsurf / Devin Desktop',
+    kind: 'guarded-file',
+    sourcePath: '.windsurf/rules/agentic-senior-core.md',
+    targetPath: () => path.join(HOME, '.codeium', 'windsurf', 'memories', 'global_rules.md'),
+    note: 'Single global file (6,000 char limit). Skipped if you already have your own global_rules.md.',
+  },
+  copilot: {
+    label: 'GitHub Copilot (VS Code)',
+    kind: 'copilot-user-instructions',
+    sourcePath: '.github/copilot-instructions.md',
+    targetPath: () => path.join(vscodeUserPromptsDirectory(), 'agentic-senior-core.instructions.md'),
+    note: 'Installs into the VS Code default profile. Other profiles need their own copy.',
+  },
+};
+
+const MANUAL_TARGETS = [
+  { label: 'Cursor', hint: 'Settings > Rules > User Rules: paste the contents of AGENTS.md (plain text only, no global rules file support).' },
+  { label: 'Zed', hint: 'Rules Library (Agent Panel): create a rule from AGENTS.md and mark it as default (paper clip icon).' },
+  { label: 'Continue', hint: 'Global config.yaml: add a rules block referencing AGENTS.md content.' },
+  { label: 'Aider', hint: `~/.aider.conf.yml: add "read: ${path.join(REPOSITORY_ROOT, 'CONVENTIONS.md')}" (absolute path auto-updates with npm).` },
+];
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function installGlobalTarget(targetKey) {
+  const target = GLOBAL_TARGETS[targetKey];
+  const sourcePath = path.join(REPOSITORY_ROOT, target.sourcePath);
+  const targetPath = target.targetPath();
+
+  if (!(await pathExists(sourcePath))) {
+    console.error(`  ${target.label}: source not found (${sourcePath}) ... FAIL`);
+    return false;
+  }
+
+  if (target.kind === 'directory') {
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.cp(sourcePath, targetPath, { recursive: true, force: true });
+    console.log(`  ${target.label}: ${targetPath} ... OK`);
+    return true;
+  }
+
+  if (target.kind === 'guarded-file') {
+    if (await pathExists(targetPath)) {
+      const existingContent = await fs.readFile(targetPath, 'utf8');
+      if (!existingContent.startsWith(ASC_MARKER)) {
+        console.log(`  ${target.label}: existing ${path.basename(targetPath)} found (not ASC) ... SKIPPED`);
+        console.log('    Append the contents of AGENTS.md manually to keep your own rules.');
+        return false;
+      }
+    }
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.copyFile(sourcePath, targetPath);
+    console.log(`  ${target.label}: ${targetPath} ... OK`);
+    return true;
+  }
+
+  if (target.kind === 'copilot-user-instructions') {
+    const rulesContent = await fs.readFile(sourcePath, 'utf8');
+    const instructionsContent = `---\napplyTo: '**'\n---\n\n${rulesContent}`;
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, instructionsContent);
+    console.log(`  ${target.label}: ${targetPath} ... OK`);
+    return true;
+  }
+
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.copyFile(sourcePath, targetPath);
+  console.log(`  ${target.label}: ${targetPath} ... OK`);
+  return true;
+}
+
+function printGlobalUsage() {
+  console.log('Agentic Senior Core -- Global Install\n');
+  console.log('Installs rules to user-level locations. Applies to ALL projects, zero project files.\n');
+  console.log('Usage: asc global [--antigravity] [--cline] [--kilocode] [--kiro] [--openhands] [--windsurf] [--copilot] [--roo] [--all]\n');
+  console.log('Available targets:');
+  for (const [key, target] of Object.entries(GLOBAL_TARGETS)) {
+    console.log(`  --${key.padEnd(12)} ${target.label.padEnd(28)} -> ${target.targetPath()}`);
+  }
+  console.log('\nManual setup (no global rules file support):');
+  for (const manual of MANUAL_TARGETS) {
+    console.log(`  ${manual.label.padEnd(10)} ${manual.hint}`);
+  }
+  console.log('\nNote: these are static copies. After npm update -g, re-run asc global to refresh.');
+}
+
+export async function runGlobalCommand(commandArguments) {
+  const requestedTargets = [];
+
+  for (const argument of commandArguments) {
+    if (argument === '--all') {
+      requestedTargets.push(...Object.keys(GLOBAL_TARGETS));
+      break;
+    }
+
+    const targetKey = argument.replace(/^--/, '');
+    if (GLOBAL_TARGETS[targetKey]) {
+      requestedTargets.push(targetKey);
+    } else if (argument.startsWith('--')) {
+      console.error(`Unknown option: ${argument}`);
+      console.log(`Available targets: ${Object.keys(GLOBAL_TARGETS).map(k => `--${k}`).join(', ')}, --all`);
+      process.exit(1);
+    }
+  }
+
+  if (requestedTargets.length === 0) {
+    printGlobalUsage();
+    return;
+  }
+
+  console.log('Agentic Senior Core -- Installing global rules\n');
+
+  let successCount = 0;
+  for (const targetKey of requestedTargets) {
+    const success = await installGlobalTarget(targetKey);
+    if (success) successCount++;
+    const note = GLOBAL_TARGETS[targetKey].note;
+    if (note) console.log(`    ${note}`);
+  }
+
+  console.log(`\n${successCount}/${requestedTargets.length} global target(s) installed.`);
+  console.log('Static copies do not auto-update: re-run asc global after npm update -g.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "5.6.0",
+  "version": "5.8.0",
   "type": "module",
   "description": "Universal AI coding rules. Write code like a staff engineer, not a junior.",
   "bin": {
@@ -11,6 +11,7 @@
   "files": [
     "bin/",
     "lib/cli/commands/adapter.mjs",
+    "lib/cli/commands/global.mjs",
     "lib/cli/commands/clean.mjs",
     "lib/cli/commands/uninstall.mjs",
     "lib/cli/commands/status.mjs",
@@ -87,6 +88,6 @@
     "agentic"
   ],
   "scripts": {
-    "test": "node --test ./tests/adapter.test.mjs"
+    "test": "node --test ./tests/adapter.test.mjs ./tests/path-hash.test.mjs"
   }
 }

package/plugin.yaml

@@ -1,5 +1,5 @@
 name: agentic-senior-core
-version: 5.6.0
+version: 5.8.0
 description: Universal AI coding rules. Write code like a staff engineer.
 author: fatidaprilian
 provides_hooks:

package/scripts/mcp-server/tools.mjs

@@ -5,6 +5,9 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { dirname, resolve, sep } from 'node:path';
+import { createRequire } from 'node:module';
+const requireCJS = createRequire(import.meta.url);
+const pathUtil = requireCJS('../../hooks/path-util.cjs');
 import {
   AVAILABLE_TEST_SUITES,
   DEFAULT_FETCH_MAX_CHARS,
@@ -377,6 +380,13 @@ function resolveStatePath(relativeStatePath) {
     throw new Error('path is required and must be relative to .agent-context/state');
   }
 
+  if (normalizedRelativePath === 'workflow-gate.json') {
+    return {
+      normalizedRelativePath,
+      resolvedStatePath: pathUtil.getWorkflowGatePath(REPOSITORY_ROOT),
+    };
+  }
+
   const resolvedStatePath = resolve(STATE_DIRECTORY, normalizedRelativePath);
   const stateRootPrefix = `${STATE_DIRECTORY}${sep}`;
   if (resolvedStatePath !== STATE_DIRECTORY && !resolvedStatePath.startsWith(stateRootPrefix)) {

package/skills/asc/SKILL.md

@@ -4,6 +4,8 @@ Universal AI coding rules. Write code like a staff engineer.
 
 ## Available Commands
 
+- `/asc-new-project` -- Greenfield workflow (Define -> Spec -> Implement -> Validate)
+- `/asc-add-feature` -- Brownfield workflow (Research -> Plan -> Implement)
 - `/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
@@ -17,8 +19,9 @@ On plugin-tier hosts (Claude Code, Codex CLI, Copilot CLI), a PostToolUse hook f
 - New dependencies against stdlib duplicates (decision ladder step 3)
 - LOC delta > 30 lines on edits (step 5)
 - New files > 50 lines (steps 1–2)
+- Workflow gate violations: source/config edits during research or plan phases
 
-Violations inject a nudge referencing the specific ladder step. The hook is silent when no issues are found.
+Violations inject a nudge referencing the specific ladder step or workflow phase. The hook is silent when no issues are found. All enforcement is advisory — nudges, not hard blocks.
 
 ## What It Does
 

package/skills/asc-add-feature/SKILL.md

@@ -0,0 +1,46 @@
+# Add Feature Workflow
+
+Structured brownfield workflow. Adapted from QRSPI to prevent context rot and ensure alignment before building.
+
+Grounded in: RPI (Dex Horthy, HumanLayer 2025) with corrections from QRSPI 8-stage evolution (Coding Agents Conference, March 2026). Plan-reading illusion fix and instruction budget constraint applied. Stages 2/5/7 adapted; stages 1/3/4/6/8 skipped as too heavyweight for individual-developer workflow.
+
+## Gate Mechanism
+
+This workflow nudges the agent to stop at each phase boundary, same enforcement tier as the existing decision ladder — not a hard block. Bypasses are logged to the debt ledger.
+
+**Known limitation:** Bypass-to-debt-ledger logging is self-reported by the agent, not enforced by the hook. The PostToolUse hook has no MCP access — it nudges the agent to log, but cannot write the debt entry itself.
+
+To track phase, write to `workflow-gate.json` via the `state_write` MCP tool.
+Format:
+```json
+{
+  "workflow": "asc-add-feature",
+  "phase": "<current_phase>",
+  "updatedAt": "<ISO-timestamp>"
+}
+```
+
+## Phase 1: Research (No Code Changes)
+
+1. Write `workflow-gate.json` with phase `research`.
+2. Map existing code: patterns, utilities, dependencies already in use.
+3. Identify what must NOT be rebuilt (e.g., existing validation helpers).
+4. Output a factual research summary.
+5. **STOP and wait for user approval.** Do not plan or implement.
+
+## Phase 2: Plan
+
+1. On approval of Phase 1, update `workflow-gate.json` phase to `plan`.
+2. Create a numbered, step-by-step implementation plan with specific files, functions, and line references.
+3. Include a "Don't Build" list from the research phase.
+4. **Callout: Plan-Reading Illusion.** Ask the user to explicitly verify the plan against the codebase, not just skim it.
+5. Output the plan.
+6. **STOP and wait for user approval.** Do not implement.
+
+## Phase 3: Implement
+
+1. On approval of Phase 2, update `workflow-gate.json` phase to `implement`.
+2. Recommend a fresh context (intentional compaction) if the context window is getting full.
+3. Execute the approved plan.
+4. Validate: tests pass, no duplicate code introduced, plan items checked off.
+5. On completion, clear the state in `workflow-gate.json` by overwriting it with `{}`.

package/skills/asc-audit/SKILL.md

@@ -2,6 +2,8 @@
 
 Security and architecture audit. Deeper than review, focused on finding vulnerabilities and structural anti-patterns.
 
+Grounded in: OWASP Top 10 (2021), OWASP ASVS v4, CVSS vulnerability report structure, CWE classification.
+
 ## Audit Scope
 
 1. **Trust boundaries**: Every point where external input enters the system. Validate that inputs are sanitized, normalized, and rejected when invalid.

package/skills/asc-debt/SKILL.md

@@ -2,6 +2,8 @@
 
 Track deferred enforcement violations. When an ASC ladder nudge fires and the shortcut is accepted rather than fixed, log it here for later resolution.
 
+Grounded in: Cunningham's technical debt metaphor (1992). Entry format (ladder step + violation + status lifecycle) is an ASC-specific implementation.
+
 ## 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.

package/skills/asc-new-project/SKILL.md

@@ -0,0 +1,49 @@
+# New Project Workflow
+
+Structured greenfield workflow. Prevents building before alignment on what to build.
+
+Grounded in: Spec-Driven Development (SDD) with scaffolding-spec approach. Specs guide implementation, then the code becomes the source of truth — specs are not maintained as living documents unless the team explicitly opts in.
+
+## Gate Mechanism
+
+This workflow nudges the agent to stop at each phase boundary, same enforcement tier as the existing decision ladder — not a hard block. Bypasses are logged to the debt ledger.
+
+**Known limitation:** Bypass-to-debt-ledger logging is self-reported by the agent, not enforced by the hook. The PostToolUse hook has no MCP access — it nudges the agent to log, but cannot write the debt entry itself.
+
+To track phase, write to `workflow-gate.json` via the `state_write` MCP tool.
+Format:
+```json
+{
+  "workflow": "asc-new-project",
+  "phase": "<current_phase>",
+  "updatedAt": "<ISO-timestamp>"
+}
+```
+
+## Phase 1: Define (No Code)
+
+1. Write `workflow-gate.json` with phase `research`.
+2. Clarify with the user: tech stack, target platform, constraints, non-goals.
+3. Propose a directory structure and module boundaries.
+4. Output a project brief summarizing decisions.
+5. **STOP and wait for user approval.** Do not write specs or code.
+
+## Phase 2: Spec (No Implementation Code)
+
+1. On approval of Phase 1, update `workflow-gate.json` phase to `plan`.
+2. Write per-feature specs with acceptance criteria and edge cases.
+3. Specs are scaffolding — they guide the build, then the code is the source of truth.
+4. Output specs for review.
+5. **STOP and wait for user approval.** Do not implement.
+
+## Phase 3: Implement
+
+1. On approval of Phase 2, update `workflow-gate.json` phase to `implement`.
+2. Build against the approved specs. Apply the ASC decision ladder on every file.
+3. Run the decision ladder: does this need to exist? Does stdlib cover it? One function or full module?
+
+## Phase 4: Validate
+
+1. Run tests. Check each spec's acceptance criteria.
+2. Confirm nothing was over-built beyond what the specs required.
+3. On completion, clear the state in `workflow-gate.json` by overwriting it with `{}`.

package/skills/asc-refactor/SKILL.md

@@ -2,12 +2,33 @@
 
 Structured refactoring workflow. Preserves existing behavior while improving structure.
 
+Grounded in: Fowler's Refactoring (read-understand-smallest scope-preserve behavior), Rule of Three (abstraction threshold), YAGNI principle (XP/Kent Beck). Empirical evidence: agents dominate low-level refactors (rename, extract, type changes) but struggle with multi-file architectural changes (arXiv, 15k+ instance study).
+
+## YAGNI Scan (Before Any Restructuring)
+
+Before changing structure, scan for speculative code to remove:
+- "Just in case" logic, unused feature flags, dead branches behind config toggles.
+- Abstractions wrapping a single implementation with no second consumer.
+- Premature extension points (plugin hooks, strategy patterns) with one concrete path.
+
+Removing speculative code is the highest-value, lowest-risk refactor type.
+
+## Classify Before Proceeding
+
+After reading the target code, classify the refactor:
+
+- **Low-level** (rename, extract method, type safety, dead code removal): proceed after explaining the change. No approval gate needed.
+- **High-level** (move module, change architecture, redesign abstractions, multi-file structural changes): output a plan with specific files and rationale, then **stop and wait for user approval** before implementing.
+
+**Known limitation:** The high-level refactor gate is a skill-text instruction — the agent self-classifies and self-stops. Unlike `/asc-add-feature` and `/asc-new-project`, this gate is not backed by the PostToolUse hook or workflow-gate.json. If the agent bypasses the gate, there is no automated nudge.
+
 ## Before Editing
 
 1. Read the target code and understand existing patterns.
 2. Identify the smallest relevant scope for the refactor.
-3. If the change touches UI, check accessibility and responsive behavior.
-4. If the change touches dependencies, verify current official docs.
+3. Classify the refactor (see above). If high-level, stop and present a plan.
+4. If the change touches UI, check accessibility and responsive behavior.
+5. If the change touches dependencies, verify current official docs.
 
 ## Refactor Rules
 

package/skills/asc-reference/SKILL.md

@@ -2,6 +2,8 @@
 
 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.
 
+Grounded in: WCAG 2.2 AA (accessibility), Fowler's Money Pattern (monetary types), Nygard's Release It! (resilience patterns), AWS Well-Architected Reliability Pillar (backoff/circuit breakers), OWASP Secure Coding Practices (input validation, logging).
+
 ## Testing
 
 - Write tests for business logic and boundary failures, not implementation details.

package/skills/asc-review/SKILL.md

@@ -2,6 +2,8 @@
 
 Production-risk code review. Prioritize findings by severity.
 
+Grounded in: OWASP Risk Rating Methodology, Google Engineering Practices (code review guide), Clean Architecture (transport vs business layer separation).
+
 ## Before Reviewing
 
 1. Read the changed files and understand the scope.