@jaybeeuu/agent-cortex 1.20.0

package/skills/workflow/run-pipeline-stage/scripts/pnpm-lock.yaml

@@ -0,0 +1,342 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.17
+      tsx:
+        specifier: ^4.0.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.0.0
+        version: 5.9.3
+
+packages:
+
+  '@esbuild/aix-ppc64@0.27.7':
+    resolution: {integrity: sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.7':
+    resolution: {integrity: sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.7':
+    resolution: {integrity: sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.7':
+    resolution: {integrity: sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.7':
+    resolution: {integrity: sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.7':
+    resolution: {integrity: sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    resolution: {integrity: sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.7':
+    resolution: {integrity: sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.7':
+    resolution: {integrity: sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.7':
+    resolution: {integrity: sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.7':
+    resolution: {integrity: sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.7':
+    resolution: {integrity: sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.7':
+    resolution: {integrity: sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.7':
+    resolution: {integrity: sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.7':
+    resolution: {integrity: sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.7':
+    resolution: {integrity: sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.7':
+    resolution: {integrity: sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.7':
+    resolution: {integrity: sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.7':
+    resolution: {integrity: sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    resolution: {integrity: sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.7':
+    resolution: {integrity: sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.7':
+    resolution: {integrity: sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.7':
+    resolution: {integrity: sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.7':
+    resolution: {integrity: sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@types/node@22.19.17':
+    resolution: {integrity: sha512-wGdMcf+vPYM6jikpS/qhg6WiqSV/OhG+jeeHT/KlVqxYfD40iYJf9/AE1uQxVWFvU7MipKRkRv8NSHiCGgPr8Q==}
+
+  esbuild@0.27.7:
+    resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  get-tsconfig@4.14.0:
+    resolution: {integrity: sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+snapshots:
+
+  '@esbuild/aix-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/android-arm@0.27.7':
+    optional: true
+
+  '@esbuild/android-x64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.7':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.7':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.7':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.7':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.7':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.7':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.7':
+    optional: true
+
+  '@types/node@22.19.17':
+    dependencies:
+      undici-types: 6.21.0
+
+  esbuild@0.27.7:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.7
+      '@esbuild/android-arm': 0.27.7
+      '@esbuild/android-arm64': 0.27.7
+      '@esbuild/android-x64': 0.27.7
+      '@esbuild/darwin-arm64': 0.27.7
+      '@esbuild/darwin-x64': 0.27.7
+      '@esbuild/freebsd-arm64': 0.27.7
+      '@esbuild/freebsd-x64': 0.27.7
+      '@esbuild/linux-arm': 0.27.7
+      '@esbuild/linux-arm64': 0.27.7
+      '@esbuild/linux-ia32': 0.27.7
+      '@esbuild/linux-loong64': 0.27.7
+      '@esbuild/linux-mips64el': 0.27.7
+      '@esbuild/linux-ppc64': 0.27.7
+      '@esbuild/linux-riscv64': 0.27.7
+      '@esbuild/linux-s390x': 0.27.7
+      '@esbuild/linux-x64': 0.27.7
+      '@esbuild/netbsd-arm64': 0.27.7
+      '@esbuild/netbsd-x64': 0.27.7
+      '@esbuild/openbsd-arm64': 0.27.7
+      '@esbuild/openbsd-x64': 0.27.7
+      '@esbuild/openharmony-arm64': 0.27.7
+      '@esbuild/sunos-x64': 0.27.7
+      '@esbuild/win32-arm64': 0.27.7
+      '@esbuild/win32-ia32': 0.27.7
+      '@esbuild/win32-x64': 0.27.7
+
+  fsevents@2.3.3:
+    optional: true
+
+  get-tsconfig@4.14.0:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  resolve-pkg-maps@1.0.0: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.7
+      get-tsconfig: 4.14.0
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  typescript@5.9.3: {}
+
+  undici-types@6.21.0: {}

package/skills/workflow/run-pipeline-stage/scripts/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: true

package/skills/workflow/run-pipeline-stage/scripts/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["*.ts"]
+}

package/skills/workflow/using-agent-skills/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: using-agent-skills
+description: Routes incoming work to the right skill and enforces core agent behaviors. Use when starting a session, deciding which skill applies, or when you need to check "which skill should I use?".
+---
+
+# Using Agent Skills
+
+## When to use
+
+- Starting a new session and need to orient on available workflows.
+- A task arrives and you need to decide which skill applies.
+- The user asks "which skill should I use for this?"
+- You want to verify that core operating behaviors are being followed.
+
+## Workflow
+
+When a task arrives, identify the development phase and apply the corresponding skill:
+
+```
+Task arrives
+    │
+    ├── Don't know what to build yet? ──────→ grill-me
+    ├── Have a rough idea? ─────────────────→ record-idea
+    ├── New feature / PRD needed? ──────────→ write-a-prd
+    ├── PRD approved, need tasks? ──────────→ prd-to-tasks
+    ├── Need a single task tracked? ────────→ create-task
+    ├── Need to plan a feature end-to-end? ─→ plan
+    ├── Running beads / task execution? ────→ ralph
+    │   └── Single stage? ─────────────────→ run-pipeline-stage
+    ├── Implementing code? ────────────────→ tdd
+    │   └── Designing an interface? ───────→ design-an-interface
+    ├── Reviewing code? ───────────────────→ style-code
+    │   └── Security concerns? ────────────→ review-security
+    ├── Writing tests? ────────────────────→ style-tests
+    ├── Writing docs? ─────────────────────→ style-documentation
+    ├── Writing external comms? ───────────→ style-comms
+    ├── Stress-testing a plan? ────────────→ grill-with-docs
+    ├── Planning a refactor? ──────────────→ request-refactor-plan
+    ├── Evaluating architecture? ──────────→ technical-direction
+    ├── Finding refactor opportunities? ───→ improve-codebase-architecture
+    ├── Need task tracking? ───────────────→ bd-tool
+    ├── Need human review / HITL? ─────────→ hitl-collab
+    ├── Need a handoff doc? ───────────────→ handoff
+    ├── Writing a ticket for Jira? ────────→ write-a-ticket
+    ├── Creating a new skill? ─────────────→ write-a-skill
+    ├── Refactoring a skill? ──────────────→ refactor-skill
+    ├── Updating agent docs? ──────────────→ maintain-agent-docs
+    └── Setting up beads in a new project? → init-beads
+```
+
+## Core Operating Behaviors
+
+These behaviors apply at all times, across all skills. They are non-negotiable.
+
+### 1. Surface Assumptions
+
+Before implementing anything non-trivial, explicitly state your assumptions. Don't silently fill in ambiguous requirements — surface uncertainty early, it's cheaper than rework.
+
+### 2. Manage Confusion Actively
+
+When you encounter inconsistencies, conflicting requirements, or unclear specifications: **STOP**. Name the specific confusion, present the tradeoff or ask the clarifying question, and wait for resolution before continuing.
+
+### 3. Push Back When Warranted
+
+You are not a yes-machine. When an approach has clear problems, point out the issue directly, explain the concrete downside, propose an alternative, and accept the human's decision if they override with full information.
+
+### 4. Enforce Simplicity
+
+Your natural tendency is to overcomplicate. Before finishing any implementation, ask: Can this be done in fewer lines? Are these abstractions earning their complexity? Prefer the boring, obvious solution.
+
+### 5. Maintain Scope Discipline
+
+Touch only what you're asked to touch. Do not clean up orthogonal code, refactor adjacent systems, or add features not in the spec. Surgical precision, not unsolicited renovation.
+
+### 6. Verify, Don't Assume
+
+A task is not complete until verification passes. "Seems right" is never sufficient — there must be evidence: passing tests, build output, or runtime data.
+
+## Lifecycle Sequence
+
+For a complete feature, the typical skill sequence is:
+
+1. `grill-me` → Extract what the user actually wants
+2. `record-idea` → Refine vague ideas
+3. `write-a-prd` → Define what we're building
+4. `prd-to-tasks` → Break into verifiable chunks
+5. `plan` → Orchestrate the full flow end-to-end
+6. `ralph` → Execute all pending beads
+7. `tdd` → Prove each slice works
+8. `style-code` → Review before merge
+9. `review-security` → Check for secrets
+10. `git-workflow` → Clean commit history
+
+Not every task needs every skill. A bug fix might only need: `tdd` → `style-code` → `review-security`.
+
+## Red Flags
+
+- Starting work without checking which skill applies.
+- Skipping verification because "it looks right."
+- Making wrong assumptions without stating them.
+- Overcomplicating code when a simple solution exists.
+- Modifying code orthogonal to the task scope.
+
+## Verification checklist
+
+- [ ] Correct skill identified before starting work.
+- [ ] Core operating behaviors followed throughout.
+- [ ] Verification completed with evidence (tests, build, runtime).
+- [ ] Scope limited to the task at hand.

package/skills/workflow/using-agent-skills/scripts/validate-skill-structure.test.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const SKILL_PATH = new URL("../SKILL.md", import.meta.url);
+
+function readSkill(): string {
+  return readFileSync(SKILL_PATH, "utf-8");
+}
+
+describe("using-agent-skills SKILL.md structure", () => {
+  const content = readSkill();
+
+  it("has required front-matter fields", () => {
+    expect(content).toMatch(/^---\n/);
+    expect(content).toMatch(/name:\s*using-agent-skills/);
+    expect(content).toMatch(/description:/);
+  });
+
+  it("description is ≤ 1024 characters", () => {
+    const descMatch = content.match(/description:\s*(.+)/);
+    expect(descMatch).toBeTruthy();
+    if (descMatch) {
+      expect(descMatch[1].length).toBeLessThanOrEqual(1024);
+    }
+  });
+
+  it("description includes 'Use when' trigger phrases", () => {
+    expect(content).toMatch(/Use when/i);
+  });
+
+  it("has required 'When to use' section", () => {
+    expect(content).toMatch(/## When to use/);
+  });
+
+  it("has required 'Workflow' section", () => {
+    expect(content).toMatch(/## Workflow/);
+  });
+
+  it("has required 'Verification checklist' section", () => {
+    expect(content).toMatch(/## Verification checklist/);
+  });
+
+  it("has 'Core Operating Behaviors' section", () => {
+    expect(content).toMatch(/## Core Operating Behaviors/);
+  });
+
+  it("has a skill routing decision tree", () => {
+    expect(content).toContain("Task arrives");
+    expect(content).toContain("→ ralph");
+    expect(content).toContain("→ tdd");
+  });
+
+  it("references existing agent-cortex skills", () => {
+    const expectedSkills = [
+      "ralph",
+      "plan",
+      "tdd",
+      "bd-tool",
+      "git-workflow",
+      "review-security",
+      "style-code",
+      "style-tests",
+    ];
+    for (const skill of expectedSkills) {
+      expect(content).toContain(skill);
+    }
+  });
+
+  it("is under 150 lines", () => {
+    const lines = content.split("\n");
+    expect(lines.length).toBeLessThanOrEqual(150);
+  });
+});

package/test/cli.test.mjs

@@ -0,0 +1,149 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI_PATH = join(__dirname, "..", "bin", "agent-cortex.mjs");
+
+function runCli(args) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
+      resolve({
+        exitCode: error ? error.code ?? 1 : 0,
+        stdout: stdout,
+        stderr: stderr,
+      });
+    });
+  });
+}
+
+describe("parseArgs", () => {
+  it("returns { command: 'help' } when no arguments given", () => {
+    const result = parseArgs([]);
+    assert.deepStrictEqual(result, { command: "help" });
+  });
+
+  it("returns { command: 'help' } for --help flag", () => {
+    const result = parseArgs(["--help"]);
+    assert.deepStrictEqual(result, { command: "help" });
+  });
+
+  it("returns { command: 'help' } for -h flag", () => {
+    const result = parseArgs(["-h"]);
+    assert.deepStrictEqual(result, { command: "help" });
+  });
+
+  it("returns { command: 'install', harness: 'copilot' } for install copilot", () => {
+    const result = parseArgs(["install", "copilot"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "copilot" });
+  });
+
+  it("returns { command: 'install', harness: 'claude' } for install claude", () => {
+    const result = parseArgs(["install", "claude"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "claude" });
+  });
+
+  it("returns { command: 'install', harness: 'pi' } for install pi", () => {
+    const result = parseArgs(["install", "pi"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "pi" });
+  });
+
+  it("returns { command: 'install', harness: null } when install has no harness", () => {
+    const result = parseArgs(["install"]);
+    assert.deepStrictEqual(result, { command: "install", harness: null });
+  });
+
+  it("returns { command: 'unknown', name: 'foo' } for unknown command", () => {
+    const result = parseArgs(["foo"]);
+    assert.deepStrictEqual(result, { command: "unknown", name: "foo" });
+  });
+});
+
+describe("buildHelpText", () => {
+  it("returns a string containing usage info", () => {
+    const text = buildHelpText();
+    assert.ok(typeof text === "string");
+    assert.ok(text.includes("agent-cortex"));
+    assert.ok(text.includes("install"));
+  });
+});
+
+describe("validateHarness", () => {
+  it("returns ok for supported harnesses", () => {
+    for (const h of ["copilot", "claude", "pi"]) {
+      assert.deepStrictEqual(validateHarness(h), { ok: true });
+    }
+  });
+
+  it("returns error when harness is null", () => {
+    const result = validateHarness(null);
+    assert.equal(result.ok, false);
+    assert.ok(result.error.includes("Missing harness"));
+  });
+
+  it("returns error for unknown harness", () => {
+    const result = validateHarness("docker");
+    assert.equal(result.ok, false);
+    assert.ok(result.error.includes("Unknown harness"));
+  });
+});
+
+describe("CLI integration", () => {
+  it("exits 0 and prints help when run with no arguments", async () => {
+    const { exitCode, stdout } = await runCli([]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("agent-cortex"));
+    assert.ok(stdout.includes("install"));
+  });
+
+  it("exits 0 and prints help for --help", async () => {
+    const { exitCode, stdout } = await runCli(["--help"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("Usage:"));
+  });
+
+  it("exits 0 and prints help for -h", async () => {
+    const { exitCode, stdout } = await runCli(["-h"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("Usage:"));
+  });
+
+  it("exits 0 for install copilot", async () => {
+    const { exitCode, stdout } = await runCli(["install", "copilot"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("copilot"));
+  });
+
+  it("exits 0 for install claude", async () => {
+    const { exitCode, stdout } = await runCli(["install", "claude"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("claude"));
+  });
+
+  it("exits 0 for install pi", async () => {
+    const { exitCode, stdout } = await runCli(["install", "pi"]);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes("pi"));
+  });
+
+  it("exits 1 and prints error for install with no harness", async () => {
+    const { exitCode, stderr } = await runCli(["install"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Missing harness"));
+  });
+
+  it("exits 1 and prints error for install with unknown harness", async () => {
+    const { exitCode, stderr } = await runCli(["install", "docker"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Unknown harness"));
+  });
+
+  it("exits 1 and prints error for unknown command", async () => {
+    const { exitCode, stderr } = await runCli(["bogus"]);
+    assert.equal(exitCode, 1);
+    assert.ok(stderr.includes("Unknown command"));
+  });
+});