@jaybeeuu/agent-cortex 1.20.0 → 1.37.1

package/.beads/metadata.json

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

package/.github/workflows/publish.yml

@@ -1,36 +0,0 @@
-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/docs/ideas/auto-model-selection.md

@@ -1,75 +0,0 @@
-# Idea: Auto-Model Selection Plugin
-
-## Status
-Backlog idea (not implementation-ready) — **direction: evaluate and adopt existing package**
-
-## Why it might be useful
-PI has no intelligent model selection. Users must manually choose models, which means they either over-provision (expensive models for simple tasks) or under-provision (weak models for complex work). Rate limits hit without warning, forcing manual model switching mid-session. An auto-selection plugin would optimize cost/performance by matching model capability to task complexity, and provide seamless fallbacks when rate limits are hit.
-
-## How we might do it
-**Evaluate and adopt an existing PI extension** rather than building from scratch. The ecosystem already has well-maintained packages that cover task-based routing and rate-limit fallbacks. The goal is to:
-
-1. **Evaluate the top candidates** (see "Packages to evaluate" below)
-2. **Pick the best fit** for agent-cortex's workflow (beads, pipeline stages, HITL/AFK classification)
-3. **Install and configure** it, possibly with light customisation if needed
-4. **Document** the chosen package and configuration in agent-cortex docs
-
-## Packages to evaluate (in priority order)
-**Top candidates — cover both task-based routing AND fallbacks:**
-1. **`@kylebrodeur/pi-model-router`** — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallback chains and rate-limit recovery. Well-documented fork of yeliu84's original.
-2. **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies, and quota-aware fallback.
-3. **`pi-tiered-router`** — routes different *phases* (planner/validator/executor/tool-parser) to different models. Quality-first, not cost-saving.
-
-**Fallback-only (simpler, if routing is overkill):**
-- **`pi-auto-models`** — Claude→Codex quota switching with 429/529 recovery
-- **`pi-provider-fallback`** — cross-provider fallback chain with TUI config
-
-**Evaluation criteria:**
-- Does it integrate cleanly with PI's existing provider/model system?
-- Does it respect user's explicit model choice, or override it?
-- How does it handle context window mismatches on fallback?
-- Is it configurable per-project?
-- Does it have fallback chains or just single fallback?
-- Rate-limit detection and retry logic
-- Documentation quality and maintenance status
-
-## When to think about it
-- After current feature stabilisation (refactor-to-template epic, npm publishing, system prompt improvements)
-- Not blocked, but benefits from stable extension infrastructure
-
-## Priority
-Medium / backlog — valuable for cost optimisation and reliability, but not urgent. Current manual model selection works, just isn't optimal.
-
-## Open questions
-- How to classify task complexity? Heuristics (file count, prompt length, keywords)? Or let user tag tasks?
-- What defines a "model class"? Cost tier, context window size, reasoning capability, speed?
-- Should the plugin override the user's explicit model choice, or only activate when no model is selected?
-- How to handle context window mismatches when falling back (e.g., 200k → 128k)?
-- Should this be configurable per-project (different policies for different repos)?
-
-## Existing packages in the ecosystem
-Several published packages already address parts of this problem:
-
-### Fallback / rate-limit recovery
-- **`pi-provider-fallback`** — cross-provider fallback with interactive TUI config
-- **`pi-auto-models`** — primary/fallback switching on quota (Claude→Codex default), 429/529 recovery
-
-### Task-based / tier routing
-- **`pi-model-router`** (yeliu84, forked by @kdejaeger and @kylebrodeur) — per-turn routing to high/medium/low tiers based on task intent, context size, budget, with automatic fallbacks
-- **`pi-model-auto`** — routes by Low/Medium/High/Ultra capability modes per turn
-- **`pi-tiered-router`** — routes different phases (planner/validator/executor/tool-parser) to different models
-
-### Full auto-router with failover
-- **`pi-auto-router`** — multi-provider routing with same-request failover, budget-aware policies
-- **`@ifi/pi-extension-adaptive-routing`** — adaptive routing with local telemetry persistence
-
-### Model selection (manual)
-- **`pi-model-switch`** — direct model switching tool
-- **`pi-model-select`** — `/select-model` with favourites and fuzzy search
-
-## Notes
-- **The ecosystem is active** — this space is already well-served. Before building, evaluate whether an existing package (especially `pi-model-router` or `pi-auto-router`) already meets the need.
-- **Gap analysis needed**: compare existing packages against the original requirements (task-based class selection + rate-limit fallbacks) to see if anything is genuinely missing.
-- **Partial solutions exist in PI core**: OpenRouter's routing config supports fallbacks and provider ordering, but only within OpenRouter. Cross-provider fallback requires an extension.
-- **Implementation approach** (if building): likely a PI extension that registers a "smart-router" provider, which internally delegates to real providers based on task classification and availability.
-- **Research done**: reviewed PI docs on providers, models, and extensions. Searched npm and pi.dev for existing packages.

package/docs/ideas/improve-pi-system-prompt.md

@@ -1,34 +0,0 @@
-# Idea: Improve PI System Prompt
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Why it might be useful
-PI's current system prompt is weak. Agents consistently get off track, spend excessive tokens spinning their wheels or going off on tangents, fail to check in when problems are hit, and generally behave like inexperienced code goblins. This wastes tokens, slows down task completion, and forces the user to constantly redirect the agent. A stronger system prompt would produce more focused, disciplined agents that know when to stop and ask.
-
-## How we might do it
-Build improved behavioural instructions into agent-cortex — layered on top of or replacing PI's default system prompt. Key improvements:
-
-1. **Loop prevention / circuit-breakers** — hard limits on retry attempts (e.g. 2-attempt limit before stopping and asking), no repeated tool execution without rationale
-2. **Task-focus discipline** — stronger scoping instructions, no tangential refactoring, atomic changes
-3. **Check-in triggers** — explicit rules for when the agent must stop and present options to the user
-
-A Gemini-generated execution protocol prompt exists as a possible starting point (see Notes), but will need significant customisation for agent-cortex.
-
-## When to think about it
-- Land the current work first (refactor-to-template epic, bead workflow polish, CI/CD pipeline)
-- **Next priority after current work** — this is urgent-ish
-
-## Priority
-High — after current work lands. Directly impacts daily productivity and token efficiency.
-
-## Open questions
-- Layer on top of PI's default prompt, or replace it entirely?
-- Should PI's current system prompt be reviewed for nonsense that can be chopped out?
-- Which guardrails from the Gemini starter are genuinely useful vs redundant with existing skills (e.g. `git-workflow` already covers destructive commands, `style-code` covers scope discipline)?
-- How should circuit-breakers interact with skills like `run-pipeline-stage` that already have structured workflows?
-
-## Notes
-- **Gemini starter prompt** exists (see conversation from 2026-08-05) covering loop prevention, action scope, context management, execution workflow order, and working state maintenance. Useful starting material but needs heavy customisation.
-- **Incompatibility to fix**: the starter's "Working State Maintenance" section proposes `.pi/PLAN.md` files for complex tasks. This is incompatible with agent-cortex — we use **beads (bd)** for task tracking and pipeline stages, not flat markdown plan files. This section needs to be replaced with bead-aware equivalents (e.g. updating bead notes, using pipeline stage state).
-- **Overlap with existing skills**: several guardrails already exist in agent-cortex skills (`git-workflow`, `style-code`, `run-pipeline-stage`). The biggest gaps are **loop prevention / circuit-breakers** and **check-in discipline** — these aren't enforced anywhere today.

package/docs/ideas/model-selector.md

@@ -1,40 +0,0 @@
-# Idea: model-selector
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-07-12
-
-## Problem
-Selecting the right model for a task is manual and brittle. When a model is unavailable (rate-limited, down, or lacking capability), there's no automatic fallback. You have to know which model IDs to type into `/model` and remember which providers offer which capabilities.
-
-## Who benefits
-Anyone using PI who runs multiple models/providers. The extension makes model selection declarative: "I want to write code" → extension picks the best available model (and falls back if limits are hit).
-
-## Proposed outcome
-A PI extension that defines an abstraction for selecting models based on task/use case. Users declare "use case → model(s) with fallbacks" in config, and the extension handles selection and failover automatically.
-
-Key capabilities:
-- **Use-case profiles**: e.g. `code`, `chat`, `review`, `architect` — each maps to a primary model + ordered fallbacks
-- **Automatic fallback**: if the primary model returns a 429 or error, drop to the next in the chain
-- **Task-based selection**: think "I want this model to write code" instead of choosing a specific model ID
-- **Configurable**: profiles defined in settings.json or a dedicated config file
-
-## Validity check
-- Evidence we already have: The existing `tiny-model.ts` lib in this repo already shows the pattern of configuring a model by provider/id string and looking it up via `modelRegistry.find()`. The PI extension API supports `before_provider_response` (for catching 429s) and `model_select` events.
-- Riskiest assumption: That use-case profiles are a useful abstraction — users may prefer to just name a model family and let fallback be implicit.
-- What would invalidate this idea: If PI adds built-in model routing/fallback, or if users find the abstraction adds confusion rather than removing it.
-
-## Constraints
-- Must not add LLM calls internally (per extension conventions in AGENTS.md)
-- Must work with the existing `modelRegistry` API — no monkey-patching
-- Storage/config should go in settings.json or `~/.pi/agent-cortex/` (global, cross-project)
-
-## Next validation step
-Sketch the config schema and test it against real usage patterns. Does the profile abstraction hold up for the models/providers you actually use?
-
-## Notes
-- Initial conversation during planning session 2026-07-12. Idea recorded as backlog, to be fleshed out when time permits.
-- Could draw on patterns from OpenRouter's routing and the existing `modelOverrides` in models.json.
-- The `notify` extension already intercepts provider responses — similar pattern for catching rate limits.

package/docs/ideas/pi-task-memory.md

@@ -1,34 +0,0 @@
-# Idea: PI Task Memory Skill
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Why it might be useful
-PI has no built-in task memory. Agents lose context between sessions — they can't track what a task has done, what decisions were made, or where they left off. A skill that persists task-scoped knowledge in structured markdown would let agents pick up work without re-discovering context from scratch, and give humans a readable audit trail they can review or promote into real documentation.
-
-## How we might do it
-**Possibly build on top of `bd remember`** rather than creating a separate storage system. Worth exploring whether `bd remember`'s existing infrastructure (persistence, cross-session survival, auto-injection) could be extended with task-scoping and structure, vs building something standalone.
-- **Task-linked** — memories keyed to specific bead/task IDs so they can be retrieved in context
-- **Progressively discoverable** — the agent recalls relevant memories as it picks up work, not all at once
-- **Structured** — consistent format that's easy to scan, edit, or promote
-- **Promotable** — easy to elevate a memory into real repo documentation (e.g. `docs/`, `AGENTS.md`) once it's proven stable
-
-If `bd remember` turns out to be the right foundation, the skill would add **task-scoping discipline, structure, and a promotion workflow** on top. But that's to be determined.
-
-## When to think about it
-- After the current skill set stabilises (refactor-to-template work, bead workflow, CI/CD pipeline)
-- Not blocked by anything, but benefits from a stable foundation
-
-## Priority
-Low / backlog — useful but not urgent. Current memory surfaces (bd remember, context-mode) cover some of the gap already.
-
-## Open questions
-- What triggers writing a memory? (Agent decides? Skill hook on task close? Specific prompts?)
-- What does "progressively discoverable" mean in practice — agent reads task memories at session start, or on-demand when picking up a task?
-- What does "elevate into docs" look like — export memory to markdown file, or just reference the memory in docs?
-- How to structure memory keys for task-scoping? (e.g. `task-<bead-id>-<topic>`, or a naming convention?)
-
-## Notes
-- **What bd remember already provides**: persistent cross-session memories, auto-injection at `bd prime`, searchable via `bd memories <keyword>`, stored in Dolt database.
-- **Worth exploring**: could this skill layer task-scoping discipline (memories keyed to bead IDs), structured format, progressive discovery (not all memories at once), and a promotion workflow on top of `bd remember`? Or does it need its own system?
-- Could be a **PI extension** (event hooks) rather than a skill (invoked on-demand) if memories should be written automatically during task work.

package/docs/ideas/qa-extension.md

@@ -1,43 +0,0 @@
-# Idea: qa-extension
-
-## Status
-Backlog idea (not implementation-ready)
-
-## Created
-2026-07-12
-
-## Problem
-When an agent needs clarification during a task (e.g. during a grilling session, resolving ambiguity, or making a recommendation), it has no structured way to ask the user a question and wait for an answer. The current workaround is unstructured prompting — the agent guesses, rambles, or proceeds with incomplete information. This makes grilling sessions less productive and wastes turns.
-
-## Who benefits
-Anyone using PI agents for interactive work — especially during planning, grilling, and design sessions where the model needs to ask a series of questions one at a time and get focused answers.
-
-## Proposed outcome
-A PI extension that registers a `qa` or `ask` tool that the LLM can call to ask the user a question. The tool:
-- Presents the question (and optionally multiple-choice options or a recommendation)
-- Pauses the agent and waits for the user's response
-- Returns the user's answer to the model so it can continue
-- Supports multi-turn Q&A sessions (series of questions)
-
-This mirrors the built-in `ask_clarification` / `question` tools in Claude Code, GitHub Copilot Chat, and similar coding agents.
-
-## Validity check
-- Evidence we already have: The PI extension API supports custom tools with user interaction via `ctx.ui` (input, confirm, select). The `subagent` extension already demonstrates complex async tool patterns. Claude Code and Copilot both ship this — it's a proven pattern.
-- Riskiest assumption: That the tool execution model in PI can support a "pause and wait for user input" flow without blocking the agent loop awkwardly.
-- What would invalidate this idea: If PI adds a built-in `ask_user` tool, or if the UX of blocking the agent loop for input feels worse than the current unstructured approach.
-
-## Constraints
-- Must work in both TUI and RPC modes (graceful fallback in non-interactive modes)
-- Should support at minimum: free-text input, confirm/deny, and multiple-choice selection
-- Questions and answers should be visible in the session history so they survive compaction
-- Must handle abort (Ctrl+C mid-question) gracefully
-
-## Next validation step
-1. **Investigate existing extensions first** — search PI's built-in tools, extension registry, and community repos for an existing `ask`/`qa`/`question` tool before building. May already be available.
-2. If no existing extension: check the PI tool execution model to see if a custom tool can return a partial result and then receive follow-up input from the user. Look at how `ctx.ui.input()` and `ctx.ui.confirm()` behave inside tool execution — can they block and return, or do they need a different pattern?
-
-## Notes
-- **Needs investigation** — check for existing PI extensions/tools before building.
-- Initial conversation 2026-07-12. Motivated by making grilling sessions more efficient — the grill-me skill asks one question at a time, and a structured Q&A tool would make that flow tighter.
-- Related to `grill-me` skill (`skills/productivity/grill-me/SKILL.md`) — this extension could become the runtime that grill-me delegates its questioning to.
-- Possible names: `/ask`, `qa`, `question` tool.

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

@@ -1,109 +0,0 @@
----
-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

@@ -1,73 +0,0 @@
-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);
-  });
-});