@jaybeeuu/agent-cortex 1.20.0

package/.beads/metadata.json

@@ -0,0 +1,7 @@
+{
+  "database": "dolt",
+  "backend": "dolt",
+  "dolt_mode": "embedded",
+  "dolt_database": "agent_nexus",
+  "project_id": "93f3bc0f-49ea-4b82-b8a8-c65875fdfdf7"
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "jaybeeuu",
+  "owner": {
+    "name": "jaybeeuu"
+  },
+  "metadata": {
+    "description": "jaybeeuu's personal Claude Code plugins."
+  },
+  "plugins": [
+    {
+      "name": "agent-cortex",
+      "source": "./claude",
+      "description": "Personal Claude Code plugin with custom agents and skills"
+    }
+  ]
+}

package/.github/workflows/ci.test.ts

@@ -0,0 +1,217 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+const ROOT = join(import.meta.dirname, "..", "..");
+
+function loadYaml(relPath: string): Record<string, unknown> {
+  const fullPath = join(ROOT, relPath);
+  assert.ok(existsSync(fullPath), `${relPath} does not exist`);
+  const content = readFileSync(fullPath, "utf-8");
+  return parseYaml(content) as Record<string, unknown>;
+}
+
+function loadJson(relPath: string): Record<string, unknown> {
+  const fullPath = join(ROOT, relPath);
+  assert.ok(existsSync(fullPath), `${relPath} does not exist`);
+  const content = readFileSync(fullPath, "utf-8");
+  return JSON.parse(content) as Record<string, unknown>;
+}
+
+// ─── CI Workflow ─────────────────────────────────────────────────────────────
+
+describe("CI workflow", () => {
+  const ci = loadYaml(".github/workflows/ci.yml") as Record<string, unknown>;
+
+  it("triggers on push to main and pull requests", () => {
+    const on = ci.on as Record<string, unknown>;
+    assert.ok(on.push, "has push trigger");
+    assert.ok("pull_request" in on, "has pull_request trigger");
+
+    const push = on.push as Record<string, unknown>;
+    assert.deepStrictEqual(push.branches, ["main"]);
+  });
+
+  it("has a job that runs on ubuntu-latest", () => {
+    const jobs = ci.jobs as Record<string, unknown>;
+    const jobNames = Object.keys(jobs);
+    assert.ok(jobNames.length > 0, "has at least one job");
+
+    const firstJob = jobs[jobNames[0]] as Record<string, unknown>;
+    assert.equal(firstJob["runs-on"], "ubuntu-latest");
+  });
+
+  it("checks out code", () => {
+    const steps = getSteps(ci);
+    const checkout = steps.find(
+      (s: Record<string, unknown>) => s.name === "Checkout"
+    );
+    assert.ok(checkout, "has Checkout step");
+    const uses = (checkout as Record<string, unknown>).uses as string;
+    assert.ok(uses.startsWith("actions/checkout@"), "uses actions/checkout");
+  });
+
+  it("sets up Node.js", () => {
+    const steps = getSteps(ci);
+    const setupNode = steps.find(
+      (s: Record<string, unknown>) => s.name === "Setup Node"
+    );
+    assert.ok(setupNode, "has Setup Node step");
+  });
+
+  it("sets up pnpm", () => {
+    const steps = getSteps(ci);
+    const setupPnpm = steps.find(
+      (s: Record<string, unknown>) => s.name === "Setup pnpm"
+    );
+    assert.ok(setupPnpm, "has Setup pnpm step");
+    const uses = (setupPnpm as Record<string, unknown>).uses as string;
+    assert.ok(uses.startsWith("pnpm/action-setup@"), "uses pnpm/action-setup");
+  });
+
+  it("installs dependencies", () => {
+    const steps = getSteps(ci);
+    const install = steps.find(
+      (s: Record<string, unknown>) => s.name === "Install dependencies"
+    );
+    assert.ok(install, "has Install dependencies step");
+  });
+
+  it("runs lint", () => {
+    const steps = getSteps(ci);
+    const lint = steps.find(
+      (s: Record<string, unknown>) => s.name === "Lint"
+    );
+    assert.ok(lint, "has Lint step");
+  });
+
+  it("runs tests", () => {
+    const steps = getSteps(ci);
+    const test = steps.find(
+      (s: Record<string, unknown>) => s.name === "Test"
+    );
+    assert.ok(test, "has Test step");
+  });
+
+  it("runs build", () => {
+    const steps = getSteps(ci);
+    const build = steps.find(
+      (s: Record<string, unknown>) => s.name === "Build"
+    );
+    assert.ok(build, "has Build step");
+  });
+});
+
+// ─── Publish Workflow ────────────────────────────────────────────────────────
+
+describe("Publish workflow", () => {
+  const publish = loadYaml(
+    ".github/workflows/publish.yml"
+  ) as Record<string, unknown>;
+
+  it("triggers on release published", () => {
+    const on = publish.on as Record<string, unknown>;
+    assert.ok(on.release, "has release trigger");
+    const release = on.release as Record<string, unknown>;
+    assert.deepStrictEqual(release.types, ["published"]);
+  });
+
+  it("has a job that runs on ubuntu-latest", () => {
+    const jobs = publish.jobs as Record<string, unknown>;
+    const jobNames = Object.keys(jobs);
+    assert.ok(jobNames.length > 0, "has at least one job");
+
+    const firstJob = jobs[jobNames[0]] as Record<string, unknown>;
+    assert.equal(firstJob["runs-on"], "ubuntu-latest");
+  });
+
+  it("sets up Node 24 with setup-node v6 for OIDC", () => {
+    const steps = getSteps(publish);
+    const setupNode = steps.find(
+      (s: Record<string, unknown>) => s.name === "Setup Node"
+    );
+    assert.ok(setupNode, "has Setup Node step");
+    const uses = (setupNode as Record<string, unknown>).uses as string;
+    assert.ok(uses.startsWith("actions/setup-node@v6"), "uses setup-node v6");
+    const with_ = (setupNode as Record<string, unknown>).with as Record<
+      string,
+      unknown
+    >;
+    assert.equal(with_["node-version"], 24);
+    assert.equal(
+      with_["registry-url"],
+      undefined,
+      "no registry-url — OIDC auth needs no registry config"
+    );
+  });
+
+  it("packs the tarball then publishes with npm", () => {
+    const steps = getSteps(publish);
+    const publishStep = steps.find(
+      (s: Record<string, unknown>) => s.name === "Publish to npm"
+    );
+    assert.ok(publishStep, "has Publish to npm step");
+    const run = (publishStep as Record<string, unknown>).run as string;
+    assert.ok(run.includes("pnpm pack"), "packs with pnpm");
+    assert.ok(run.includes("npm publish"), "publishes with npm");
+    assert.ok(!run.includes("pnpm publish"), "does not publish via pnpm");
+  });
+
+  it("grants contents: read and id-token: write permissions for OIDC", () => {
+    const jobs = publish.jobs as Record<string, unknown>;
+    const jobNames = Object.keys(jobs);
+    const job = jobs[jobNames[0]] as Record<string, unknown>;
+    const permissions = job.permissions as Record<string, unknown>;
+    assert.equal(permissions["contents"], "read");
+    assert.equal(permissions["id-token"], "write");
+  });
+
+  it("has no NPM_TOKEN secret or NODE_AUTH_TOKEN auth", () => {
+    const content = readFileSync(
+      join(ROOT, ".github/workflows/publish.yml"),
+      "utf-8"
+    );
+    assert.ok(!content.includes("NPM_TOKEN"), "no NPM_TOKEN secret reference");
+    assert.ok(
+      !content.includes("NODE_AUTH_TOKEN"),
+      "no NODE_AUTH_TOKEN auth env"
+    );
+  });
+});
+
+// ─── Package.json ────────────────────────────────────────────────────────────
+
+describe("package.json", () => {
+  const pkg = loadJson("package.json") as Record<string, unknown>;
+
+  it("is not private (publishable to npm)", () => {
+    assert.equal(pkg.private, undefined, "package is not private");
+  });
+
+  it("has a build script", () => {
+    const scripts = pkg.scripts as Record<string, unknown>;
+    assert.ok(scripts.build, "has build script");
+  });
+
+  it("has a lint script", () => {
+    const scripts = pkg.scripts as Record<string, unknown>;
+    assert.ok(scripts.lint, "has lint script");
+  });
+
+  it("has publishConfig with public access", () => {
+    const publishConfig = pkg.publishConfig as Record<string, unknown>;
+    assert.ok(publishConfig, "has publishConfig");
+    assert.equal(publishConfig.access, "public");
+  });
+});
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getSteps(workflow: Record<string, unknown>): Record<string, unknown>[] {
+  const jobs = workflow.jobs as Record<string, unknown>;
+  const jobNames = Object.keys(jobs);
+  const firstJob = jobs[jobNames[0]] as Record<string, unknown>;
+  return firstJob.steps as Record<string, unknown>[];
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Lint
+        run: pnpm lint
+      - name: Test
+        run: pnpm test
+      - name: Build
+        run: pnpm build
+      - name: Check generated Claude plugin is up to date
+        run: |
+          pnpm build:claude
+          git diff --exit-code claude/agents/ claude/skills/

package/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Lint
+        run: pnpm lint
+      - name: Test
+        run: pnpm test
+      - name: Build
+        run: pnpm build
+      - name: Publish to npm
+        run: |
+          TARBALL=$(pnpm pack | tail -n 1)
+          npm publish "$TARBALL"

package/.junie/guidelines.md

@@ -0,0 +1,87 @@
+# Beads Issue Tracking Instructions
+
+This project uses **Beads (bd)** for issue tracking. Use the bd CLI or MCP tools for all task management.
+
+## Core Workflow Rules
+
+1. **Track ALL work in bd** - Never use markdown TODOs or comment-based task lists
+2. **Check ready work first** - Run `bd ready` to find unblocked issues
+3. **Always include descriptions** - Provide meaningful context when creating issues
+4. **Link discovered work** - Use `discovered-from` dependencies for issues found during work
+5. **Sync at session end** - Run `bd dolt push` before ending your session
+
+## Quick Command Reference
+
+### Finding Work
+```bash
+bd ready              # Show unblocked issues ready for work
+bd list --status open # List all open issues
+bd show <id>          # View issue details
+bd blocked            # Show blocked issues and their blockers
+```
+
+### Creating Issues
+```bash
+bd create "Title" --description="Details" -t bug|feature|task -p 0-4 --json
+bd create "Found bug" --description="Details" --deps discovered-from:bd-42 --json
+```
+
+### Working on Issues
+```bash
+bd update <id> --claim               # Claim work atomically
+bd update <id> --priority 1          # Change priority
+bd close <id> --reason "Completed"   # Mark complete
+```
+
+### Dependencies
+```bash
+bd dep add <issue> <depends-on>      # Add dependency (issue depends on depends-on)
+bd dep add <issue> <depends-on> --type=related  # Soft link
+```
+
+### Syncing
+```bash
+bd dolt push  # ALWAYS run at session end - commits and pushes changes
+```
+
+## Issue Types
+
+- `bug` - Something broken that needs fixing
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature composed of multiple issues
+- `chore` - Maintenance work (dependencies, tooling)
+
+## Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+## MCP Tools Available
+
+If the MCP server is configured, you can use these tools directly:
+- `mcp_beads_ready` - Find ready tasks
+- `mcp_beads_list` - List issues with filters
+- `mcp_beads_show` - Show issue details
+- `mcp_beads_create` - Create new issues
+- `mcp_beads_update` - Update issue status/priority
+- `mcp_beads_close` - Close completed issues
+- `mcp_beads_dep` - Manage dependencies
+- `mcp_beads_blocked` - Show blocked issues
+- `mcp_beads_stats` - Get issue statistics
+
+## Important Rules
+
+- ✅ Use bd for ALL task tracking
+- ✅ Always use `--json` flag for programmatic use
+- ✅ Link discovered work with `discovered-from` dependencies
+- ✅ Check `bd ready` before asking "what should I work on?"
+- ✅ Run `bd dolt push` at end of session
+- ❌ Do NOT create markdown TODO lists
+- ❌ Do NOT use external issue trackers
+- ❌ Do NOT duplicate tracking systems
+
+For more details, run `bd --help` or see the project's AGENTS.md file.

package/.junie/mcp/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "beads": {
+      "args": [
+        "mcp"
+      ],
+      "command": "bd"
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,102 @@
+# AGENTS.md
+
+Instructions for agents working on this repository.
+
+## What This Repo Is
+
+A personal Copilot CLI plugin containing custom agents and skills, plus PI extensions for
+enhancing the coding agent runtime. Changes here affect the behaviour of every agent, skill,
+and PI extension available in the author's coding sessions.
+
+## Structure
+
+```
+agent-cortex/
+├── package.json           # PI package manifest (pi: { extensions, skills })
+├── plugin.json            # GitHub Copilot plugin manifest — agents, skills, MCP servers
+├── agents/                # Custom agents (*.agent.md)
+│   └── ralph.agent.md
+├── skills/               # Grouped by domain, discovered recursively
+│   ├── planning/         # Scope, spec, decompose
+│   ├── engineering/      # The coding loop
+│   ├── productivity/     # Workflow tooling
+│   ├── style/            # Conventions and standards
+│   ├── workflow/         # Orchestration and pipeline
+│   └── review/           # Auditing and maintenance
+├── extensions/           # PI extensions (one directory per extension, each with index.ts)
+│   └── skill-stats/
+│       ├── README.md      # Installation & usage
+│       └── index.ts       # Extension entrypoint
+└── package.json          # PI package manifest (pi: { extensions, skills })
+```
+
+## Versioning
+
+**Always bump `plugin.json` version** when making any change to agents or skills. Follow
+semantic versioning:
+
+| Change type | Bump |
+|---|---|
+| New skill or agent added | `minor` |
+| Existing skill or agent meaningfully changed (new behaviour, new steps, restructured workflow) | `minor` |
+| Bug fix or clarification with no behaviour change | `patch` |
+| Breaking change (removed skill, renamed agent, incompatible workflow change) | `major` |
+
+The version bump must be included in the same commit as the change — do not leave it for a
+follow-up commit.
+
+## Changelog
+
+- Keep a root `CHANGELOG.md` for repository changes.
+- When making any repo change (agents, skills, docs, scripts, or workflow rules), update
+  `CHANGELOG.md` in the same commit.
+- Write entries under a version header that matches the bumped `plugin.json` version
+  (e.g. `## 0.40.0`). Add a new version section on every change.
+- Keep entries user-facing and outcome-focused (what changed and why it matters).
+
+## Skill Conventions
+
+- `SKILL.md` must include a YAML front-matter block with `name` and `description`.
+- `description` must be ≤ 1024 characters. First sentence: what it does. Second: "Use when…".
+- Keep `SKILL.md` under ~100 lines. Overflow into `REFERENCE.md` for rarely-needed detail.
+- Add utility scripts to `scripts/` when an operation is deterministic and would otherwise be
+  regenerated each time (e.g. install scripts, scanners).
+- Skill names use kebab-case and are grouped by prefix where related (e.g. `review-security`,
+  `review-code`; `style-code`, `style-comms`, `style-documentation`).
+
+## Agent Conventions
+
+- Agent files are named `<name>.agent.md` and live in `agents/`.
+- Keep orchestration logic in the agent file; extract shared per-task workflow into a skill
+  so it can be reused (e.g. ralph delegates per-task stage execution to `run-pipeline-stage`).
+
+## PI Extension Conventions
+
+- PI extensions live in `extensions/`, one subdirectory per extension.
+- Each extension directory contains `index.ts` (entrypoint) and `README.md` (usage).
+- Extensions are auto-discovered when the repo is installed as a PI package via `pi install`.
+- Keep extensions lightweight: no internal LLM calls. Extensions observe events and provide
+  commands — they should not add token overhead.
+- Extensions that persist data should write to `~/.pi/agent-cortex/` (global, cross-project)
+  and tag records with the project path for per-project slicing.
+
+## User preferences
+
+Before making tooling or workflow decisions, read `docs/user-preferences.md` for the
+user's personal development preferences (e.g. preferred package manager, tooling
+choices). These preferences apply across all projects where this plugin is active.
+
+## Task tracking
+
+This project uses **bd (beads)** for task tracking.
+
+Run `bd prime` at the start of each session for context.
+
+Quick reference:
+- `bd ready` — list unblocked work
+- `bd create "Title" -p <0-3>` — create a task (P0 = critical)
+- `bd update <id> --claim` — claim a task
+- `bd close <id>` — complete a task
+- `bd dep add <A> <B>` — **"A depends on B"** (B blocks A). First arg waits, second arg
+  is waited-for. To express "X blocks Y", write `bd dep add Y X`.
+- `bd dolt push` — sync to remote at session end