@jaybeeuu/agent-cortex 1.42.0 → 2.0.0

package/bin/installers/copilot.mjs

@@ -1,124 +0,0 @@
-// Install-time generator for the Copilot CLI flat agent files (agents/*.agent.md).
-// This is the single code path for producing those files from the canonical
-// composable sources — both entry points below call installCopilot(), so
-// install-time and build-time output can never diverge:
-//
-//   - bin/agent-cortex.mjs          `agent-cortex install copilot` (install-time;
-//                                   `--output <dir>` overrides the target,
-//                                   `--dry-run` plans without writing)
-//   - scripts/build-copilot-agents.mjs  `pnpm build:copilot` (dev/CI: regenerates
-//                                   the committed agents/*.agent.md files in place)
-//
-// Output lands in <root>/agents/ (the default `output`) because that is the
-// directory the Copilot plugin actually loads: plugin.json declares
-// "agents": "agents/", which scans for *.agent.md files. The generated flat
-// files therefore share the agents/ directory with the canonical composable
-// dirs they are composed from (agents/<name>/) — only flat *.agent.md files are
-// written, nothing is deleted, so a generated file can never clobber a
-// composable source. `--output` exists for the same preview/test contract as the
-// claude and pi installers: point it at a scratch dir and inspect the output.
-//
-//   agents/<name>.agent.md    composed from agents/<name>/agent.md +
-//                             agents/<name>/copilot/frontmatter.json +
-//                             agents/<name>/copilot/<section>.md ({{SECTION:...}}),
-//                             with {{TOOL:...}}/{{PATH:...}} substituted against
-//                             the copilot column of token-map.json.
-//
-// The flat files stay committed and CI drift-checks them (build:copilot +
-// git diff --exit-code -- 'agents/*.agent.md'), so a fresh clone (or a direct
-// path plugin install) ships the plugin read-ready.
-//
-// Zero dependencies so it runs on the CI Node and local Node alike.
-
-import { writeFile, mkdir, readdir } from "node:fs/promises";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
-import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
-
-const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
-const DEFAULT_ROOT = join(MODULE_DIR, "..", "..");
-
-function byName(a, b) {
-  return a.localeCompare(b);
-}
-
-/**
- * Serialise the flat-file YAML frontmatter. Field order and names mirror the
- * pre-migration flat sources (description, name, tools, argument-hint) so
- * Copilot CLI sees the same agent metadata. The GENERATED comment references
- * scripts/build-copilot-agents.mjs — the committed entry point — so the
- * generated bytes are identical whichever of the two entry points ran.
- */
-function frontmatterYaml(name, fm) {
-  const lines = [
-    "---",
-    `# GENERATED from agents/${name}/ by scripts/build-copilot-agents.mjs — DO NOT EDIT.`,
-    `description: ${JSON.stringify(fm.description)}`,
-    `name: ${JSON.stringify(fm.name)}`,
-    `tools: [${fm.tools.map((t) => JSON.stringify(t)).join(", ")}]`,
-  ];
-  if (fm.argumentHint) lines.push(`argument-hint: ${JSON.stringify(fm.argumentHint)}`);
-  lines.push("---");
-  return lines.join("\n");
-}
-
-/** Compose agents from agents/<name>/; every composable dir must ship a copilot harness. */
-async function buildAgents(root) {
-  const files = [];
-  const entries = (await readdir(join(root, "agents"), { withFileTypes: true })).sort((a, b) =>
-    byName(a.name, b.name),
-  );
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files and README
-    const dir = join(root, "agents", entry.name);
-    if (!(await isFile(join(dir, "agent.md")))) continue; // not a composable agent dir
-    if (!(await isDirectory(join(dir, "copilot"))) || !(await isFile(join(dir, "copilot", "frontmatter.json")))) {
-      throw new Error(`agent "${entry.name}": composable directory without copilot/frontmatter.json — define the copilot harness or exclude the agent`);
-    }
-
-    const fm = await composeAgent(root, entry.name, "copilot");
-    files.push({
-      name: entry.name,
-      file: `${entry.name}.agent.md`,
-      content: `${frontmatterYaml(entry.name, fm)}\n\n${fm.body}\n`,
-    });
-  }
-  return files;
-}
-
-/**
- * Generate the Copilot CLI flat agent files.
- *
- * @param {object} options
- * @param {string} [options.root]   Package root (contains agents/, token-map.json, …).
- *                                  Defaults to the repo containing this module.
- * @param {string} [options.output] Directory to write the flat *.agent.md files into
- *                                  (default: <root>/agents — the dir plugin.json's
- *                                  "agents": "agents/" scans for the plugin).
- * @param {boolean} [options.dryRun] Plan and report without writing anything.
- * @returns {{ output: string, agents: string[], dryRun: boolean }}
- */
-export async function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
-  const out = output ?? join(root, "agents");
-  const files = await buildAgents(root);
-  const summary = {
-    output: out,
-    agents: files.map((f) => f.name),
-    dryRun,
-  };
-
-  if (dryRun) {
-    console.log(`DRY-RUN — would generate into ${out}, no files written:`);
-    console.log(`  agents: ${summary.agents.join(", ")}`);
-    return summary;
-  }
-
-  await mkdir(out, { recursive: true });
-  for (const { file, content } of files) {
-    await writeFile(join(out, file), content);
-  }
-  console.log(`Generated ${files.length} Copilot agent file(s): ${summary.agents.join(", ")}`);
-  return summary;
-}

package/extensions/session-start.ts

@@ -1,44 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadSessionContext } from "./lib/context-loader.js";
-
-/**
- * Session-start extension.
- *
- * Injects baseline context at the start of every PI session:
- * 1. Skill availability hints (so the agent knows they exist)
- * 2. Project context files (AGENTS.md, user-preferences.md)
- *
- * Context files are read dynamically from the project root (cwd).
- */
-export default function (pi: ExtensionAPI) {
-  pi.on("before_agent_start", async (_event, ctx) => {
-    const skillHints = [
-      "Available skills — invoke when relevant (not pre-loaded to save context):",
-      "",
-      "• /skill:using-agent-skills — meta-skill that routes to the right skill",
-      "  and enforces core agent behaviors. Check this first if unsure.",
-      "",
-      "• /skill:bd-tool — project context & task tracking with beads.",
-      "  Run `bd ready` to see available work.",
-      "",
-      "• /skill:git-workflow — git discipline: feature branches,",
-      "  worktrees for solo AFK work, PR workflow, and when to ask.",
-      "",
-      "Read the SKILL.md for full instructions when needed.",
-    ].join("\n");
-
-    const contextFiles = loadSessionContext(ctx.cwd);
-
-    const content = contextFiles
-      ? `${skillHints}\n\n---\n\n${contextFiles}`
-      : skillHints;
-
-    return {
-      message: {
-        customType: "session-start",
-        content,
-        display: false,
-      },
-    };
-  });
-}

package/hooks.json

@@ -1,10 +0,0 @@
-{
-  "hooks": {
-    "sessionStart": [
-      {
-        "type": "prompt",
-        "prompt": "Load AGENTS.md and active beads context before taking action."
-      }
-    ]
-  }
-}

package/lib/pi-packages.mjs

@@ -1,169 +0,0 @@
-// Pi third-party package provisioning.
-//
-// agent-cortex's pi harness needs tools that live in third-party pi packages:
-// ask_questions comes from pi-questions, fetch_content from pi-web-access (see
-// token-map.json notes and docs/ideas/extension-manifests.md). Those packages
-// are declared in the package manifest — package.json → pi.packages — and this
-// module makes them real: `agent-cortex install pi` reads the declaration and
-// installs any package the pi user scope is missing.
-//
-// Provisioning goes through the pi CLI (`pi install <source>`), which both
-// installs the package under ~/.pi/agent/npm and declares it in
-// ~/.pi/agent/settings.json — the same store pi loads packages from. It is
-// opt-in (installPi option `provisionPackages`) and idempotent: a package that
-// is already declared and installed is skipped. A failed install warns and the
-// rest continue, so an offline machine never breaks the agent install.
-
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { spawn } from "node:child_process";
-
-const DEFAULT_WARN = (msg) => console.warn(`[pi-packages] ${msg}`);
-
-/**
- * Read the pi package sources agent-cortex declares it needs.
- *
- * @param {string} root Package root containing package.json
- * @returns {Promise<string[]>} Declared sources, e.g. ["npm:pi-questions"]
- */
-export async function loadRequiredPackages(root) {
-  const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf-8"));
-  const packages = manifest?.pi?.packages;
-  return Array.isArray(packages) ? packages.filter((entry) => typeof entry === "string") : [];
-}
-
-/**
- * Extract the npm package name from a pi source string.
- *
- * @param {string} source e.g. "npm:pi-web-access@0.10.7", "npm:@scope/pkg"
- * @returns {string | null} The name, or null for sources we cannot inspect locally
- */
-export function npmSourceName(source) {
-  if (typeof source !== "string" || !source.startsWith("npm:")) return null;
-  const spec = source.slice("npm:".length);
-  const at = spec.lastIndexOf("@");
-  return at > 0 ? spec.slice(0, at) : spec;
-}
-
-/**
- * Decide which required packages still need installing.
- *
- * A package is satisfied only when it is both declared in settings (so pi loads
- * it) and present in the npm store (so it is installed) — otherwise it needs a
- * `pi install` to reconcile.
- *
- * @param {string[]} required
- * @param {{ declaredSources: string[], installedNames: string[] }} state
- * @returns {string[]} The sources still to install
- */
-export function planPackageInstalls(required, { declaredSources, installedNames }) {
-  const declared = new Set(declaredSources.map(npmSourceName).filter(Boolean));
-  const installed = new Set(installedNames);
-  return required.filter((source) => {
-    const name = npmSourceName(source);
-    return name === null || !declared.has(name) || !installed.has(name);
-  });
-}
-
-/**
- * Install every required package the pi user scope is missing.
- *
- * @param {object} options
- * @param {string[]} options.required        Declared pi sources (see loadRequiredPackages)
- * @param {string} options.piRoot            Pi user scope dir (default ~/.pi/agent)
- * @param {boolean} [options.dryRun]         Report the plan without installing
- * @param {(source: string) => Promise<{ok: boolean, error: string | null}>} [options.runInstall]
- * @param {(msg: string) => void} [options.warn]
- * @returns {Promise<{planned: string[], installed: string[], failed: {source: string, error: string}[]}>}
- */
-export async function provisionPiPackages({
-  required,
-  piRoot,
-  dryRun = false,
-  runInstall = runPiInstall,
-  warn = DEFAULT_WARN,
-}) {
-  const declaredSources = await readDeclaredSources(join(piRoot, "settings.json"));
-  const installedNames = await readInstalledNames(join(piRoot, "npm", "node_modules"));
-  const planned = planPackageInstalls(required, { declaredSources, installedNames });
-
-  if (dryRun) return { planned, installed: [], failed: [] };
-
-  const installed = [];
-  const failed = [];
-  for (const source of planned) {
-    const result = await runInstall(source);
-    if (result.ok) {
-      installed.push(source);
-    } else {
-      failed.push({ source, error: result.error });
-      warn(`could not install pi package ${source}: ${result.error}`);
-    }
-  }
-  return { planned, installed, failed };
-}
-
-/** Install one pi package source through the pi CLI. */
-export function runPiInstall(source) {
-  return new Promise((resolve) => {
-    const child = spawn("pi", ["install", source], { stdio: ["ignore", "pipe", "pipe"] });
-    let stderr = "";
-    child.stdout.resume(); // drain; only failures are interesting
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk;
-    });
-    child.on("error", (err) => {
-      resolve({
-        ok: false,
-        error: err.code === "ENOENT" ? "pi CLI not found on PATH" : err.message,
-      });
-    });
-    child.on("close", (code) => {
-      resolve({
-        ok: code === 0,
-        error: code === 0 ? null : stderr.trim() || `pi install exited with code ${code}`,
-      });
-    });
-  });
-}
-
-// ─── Pi user-scope inspection ────────────────────────────────────────────────
-
-/** Read the package sources declared in a pi settings.json (missing or unreadable → none). */
-async function readDeclaredSources(settingsPath) {
-  let settings;
-  try {
-    settings = JSON.parse(await readFile(settingsPath, "utf-8"));
-  } catch {
-    // Nothing declared yet, or a file pi itself owns and repairs. Provisioning is
-    // a non-essential step — it must never fail the agent install.
-    return [];
-  }
-  const packages = Array.isArray(settings?.packages) ? settings.packages : [];
-  return packages
-    .map((entry) => (typeof entry === "string" ? entry : entry?.source))
-    .filter((source) => typeof source === "string");
-}
-
-/** List installed package names in the pi npm store (missing dir → none). */
-async function readInstalledNames(nodeModulesDir) {
-  let entries;
-  try {
-    entries = await readdir(nodeModulesDir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === "ENOENT") return [];
-    throw err;
-  }
-  const names = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    if (!entry.name.startsWith("@")) {
-      names.push(entry.name);
-      continue;
-    }
-    for (const scoped of await readdir(join(nodeModulesDir, entry.name), { withFileTypes: true })) {
-      if (scoped.isDirectory()) names.push(`${entry.name}/${scoped.name}`);
-    }
-  }
-  return names;
-}

package/plugin.json

@@ -1,35 +0,0 @@
-{
-  "name": "agent-cortex",
-  "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.42.0",
-  "author": {
-    "name": "jaybeeuu"
-  },
-  "license": "MIT",
-  "repository": "https://github.com/jaybeeuu/agent-cortex",
-  "bin": "bin/agent-cortex.mjs",
-  "agents": "agents/",
-  "skills": "skills/",
-  "mcpServers": {
-    "context7": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@upstash/context7-mcp@latest"
-      ]
-    },
-    "github": {
-      "type": "stdio",
-      "command": "pnpm",
-      "args": [
-        "dlx",
-        "@modelcontextprotocol/server-github"
-      ],
-      "tools": [
-        "*"
-      ]
-    }
-  },
-  "hooks": "hooks.json"
-}

package/scripts/build-copilot-agents.mjs

@@ -1,30 +0,0 @@
-// Regenerates the committed Copilot CLI flat agent files (agents/*.agent.md)
-// from the canonical composable agent sources (agents/<name>/).
-//
-// This script is a thin wrapper over the shared install-time generator
-// (bin/installers/copilot.mjs) — `agent-cortex install copilot` runs exactly the
-// same code path, so install-time and build-time output can never diverge. CI
-// runs this and checks `git diff --exit-code -- 'agents/*.agent.md'` to
-// guarantee the committed flat files are never stale: a fresh clone (or a
-// direct path plugin install) ships the Copilot plugin read-ready.
-//
-//   agents/<name>.agent.md    composed from agents/<name>/agent.md +
-//                             agents/<name>/copilot/frontmatter.json +
-//                             agents/<name>/copilot/<section>.md ({{SECTION:...}}),
-//                             with {{TOOL:...}}/{{PATH:...}} substituted against
-//                             the copilot column of token-map.json.
-//
-// The flat files live in the same agents/ directory the Copilot plugin scans
-// (plugin.json "agents": "agents/"), next to the composable dirs they come
-// from — the generator only writes *.agent.md files and never deletes.
-//
-// Run: pnpm build:copilot   (node scripts/build-copilot-agents.mjs)
-// Zero dependencies so it runs on the CI Node (20) and local Node alike.
-
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { installCopilot } from "../bin/installers/copilot.mjs";
-
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
-
-await installCopilot({ root: ROOT, output: join(ROOT, "agents") });

package/scripts/install-instructions.sh

@@ -1,82 +0,0 @@
-#!/usr/bin/env bash
-# Installs ~/.copilot/copilot-instructions.md with proactive skill directives.
-# Run after cloning this plugin: pnpm install (or bash scripts/install-instructions.sh)
-# Safe to re-run — replaces the agent-cortex section only.
-
-set -euo pipefail
-
-INSTRUCTIONS_FILE="$HOME/.copilot/copilot-instructions.md"
-MARKER_START="<!-- agent-cortex:start -->"
-MARKER_END="<!-- agent-cortex:end -->"
-
-BLOCK="$MARKER_START
-<!-- This block is managed by agent-cortex. Manual edits inside will be overwritten. -->
-
-## Proactive skill use (agent-cortex plugin)
-
-You have a set of custom skills available. Apply them automatically whenever they are relevant — the user should not have to invoke them by name.
-
-### Code & tests
-
-- Apply **style-code** whenever writing, editing, or reviewing code. It defines naming, module boundaries, and architectural conventions.
-- Apply **style-tests** whenever writing, editing, or reviewing tests. It defines assertion strategy, mock discipline, and what to test.
-- Apply **style-comms** whenever writing external-facing communication: tickets, RFCs, PRDs, proposals, or reports.
-- Apply **style-documentation** whenever deciding what to document or reviewing existing docs.
-- Use **tdd** (red-green-refactor loop) whenever building a new feature or fixing a bug where correctness matters.
-- Run **review-security** before committing any changes that touch secrets, auth, or credentials.
-
-### Planning & design
-
-- Use **write-a-prd** when the user wants to plan a new feature or product requirement.
-- Use **prd-to-tasks** after a PRD is approved to break it into phased epics and task beads.
-- Use **create-task** when creating a new trackable task bead.
-- Use **record-idea** when the user shares an early-stage idea that is not yet ready to implement.
-- Use **request-refactor-plan** when the user wants to plan a refactor with safe incremental commits.
-- Use **write-a-ticket** when writing a ticket for an external issue tracker (e.g. Jira).
-- Use **design-an-interface** when the user wants to explore multiple API or module designs.
-- Use **technical-direction** when evaluating architecture or technology choices with tradeoff analysis.
-- Use **grill-me** or **grill-with-docs** when the user wants to stress-test a plan or design.
-- Use **improve-codebase-architecture** when the user wants to find architectural improvement opportunities.
-
-### Task execution
-
-- Use **bd-tool** whenever the user mentions beads, bd, tasks, or asks what work is available.
-- Use **ralph** to run all pending beads end-to-end with review gates.
-- Use **run-pipeline-stage** to work through individual pipeline stages inline.
-- Use **hitl-collab** when a task requires human review, manual steps, or a PR handoff.
-- Use **classify-bead** when a bead is missing its implementation-type label.
-
-### Repo & plugin maintenance
-
-- Use **maintain-agent-docs** when reviewing or updating AGENTS.md or agent-consumed docs.
-- Use **refactor-skill** when restructuring or reviewing an existing skill.
-- Use **write-a-skill** when creating a new skill.
-- Use **init-beads** when setting up the bd task-tracker in a new project.
-
-$MARKER_END"
-
-mkdir -p "$(dirname "$INSTRUCTIONS_FILE")"
-
-if [ ! -f "$INSTRUCTIONS_FILE" ]; then
-  printf '%s\n' "$BLOCK" > "$INSTRUCTIONS_FILE"
-  echo "✓ Created $INSTRUCTIONS_FILE"
-elif grep -qF "$MARKER_START" "$INSTRUCTIONS_FILE"; then
-  # Write replacement block to a temp file so awk can read it with getline
-  BLOCK_FILE=$(mktemp)
-  printf '%s\n' "$BLOCK" > "$BLOCK_FILE"
-  awk -v start="$MARKER_START" -v end="$MARKER_END" -v blockfile="$BLOCK_FILE" '
-    $0 == start {
-      while ((getline line < blockfile) > 0) print line
-      close(blockfile)
-      skip=1; next
-    }
-    $0 == end { skip=0; next }
-    !skip     { print }
-  ' "$INSTRUCTIONS_FILE" > "${INSTRUCTIONS_FILE}.tmp"
-  mv "${INSTRUCTIONS_FILE}.tmp" "$INSTRUCTIONS_FILE"
-  rm -f "$BLOCK_FILE"
-  echo "✓ Updated agent-cortex section in $INSTRUCTIONS_FILE"
-else
-  printf '\n%s\n' "$BLOCK" >> "$INSTRUCTIONS_FILE"
-  echo "✓ Appended agent-cortex section to $INSTRUCTIONS_FILE"
-fi

package/scripts/sync-plugin-version.sh

@@ -1,17 +0,0 @@
-#!/usr/bin/env bash
-# Sync plugin.json version with package.json
-# Called by changesets after versioning to keep them in lockstep
-
-set -euo pipefail
-
-VERSION=$(node -p "require('./package.json').version")
-
-# Update plugin.json version field
-node -e "
-const fs = require('fs');
-const plugin = JSON.parse(fs.readFileSync('plugin.json', 'utf8'));
-plugin.version = '$VERSION';
-fs.writeFileSync('plugin.json', JSON.stringify(plugin, null, 2) + '\n');
-"
-
-echo "✓ Synced plugin.json to version $VERSION"