@jaybeeuu/agent-cortex 1.20.0

package/skills/engineering/improve-codebase-architecture/REFERENCE.md

@@ -0,0 +1,78 @@
+# Reference
+
+## Dependency Categories
+
+When assessing a candidate for deepening, classify its dependencies:
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a port (interface) at the module boundary. The deep module owns the logic; the transport is injected. Tests use an in-memory adapter. Production uses the real HTTP/gRPC/queue adapter.
+
+Recommendation shape: "Define a shared interface (port), implement an HTTP adapter for production and an in-memory adapter for testing, so the logic can be tested as one deep module even though it's deployed across a network boundary."
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock implementation.
+
+## Testing Strategy
+
+The core principle: **replace, don't layer.**
+
+- Old unit tests on shallow modules are waste once boundary tests exist — delete them
+- Write new tests at the deepened module's interface boundary
+- Tests assert on observable outcomes through the public interface, not internal state
+- Tests should survive internal refactors — they describe behavior, not implementation
+
+## Bead Description Template
+
+<bead-template>
+
+## Problem
+
+Describe the architectural friction:
+
+- Which modules are shallow and tightly coupled
+- What integration risk exists in the seams between them
+- Why this makes the codebase harder to navigate and maintain
+
+## Proposed Interface
+
+The chosen interface design:
+
+- Interface signature (types, methods, params)
+- Usage example showing how callers use it
+- What complexity it hides internally
+
+## Dependency Strategy
+
+Which category applies and how dependencies are handled:
+
+- **In-process**: merged directly
+- **Local-substitutable**: tested with [specific stand-in]
+- **Ports & adapters**: port definition, production adapter, test adapter
+- **Mock**: mock boundary for external services
+
+## Testing Strategy
+
+- **New boundary tests to write**: describe the behaviors to verify at the interface
+- **Old tests to delete**: list the shallow module tests that become redundant
+- **Test environment needs**: any local stand-ins or adapters required
+
+## Implementation Recommendations
+
+Durable architectural guidance that is NOT coupled to current file paths:
+
+- What the module should own (responsibilities)
+- What it should hide (implementation details)
+- What it should expose (the interface contract)
+- How callers should migrate to the new interface
+
+</bead-template>

package/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: improve-codebase-architecture
+description: Explore a codebase to find opportunities for architectural improvement, focusing on making the codebase more testable by deepening shallow modules. Use when user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more AI-navigable.
+---
+
+# Improve Codebase Architecture
+
+Explore a codebase like an AI would, surface architectural friction, discover opportunities for improving testability, and propose module-deepening refactors as beads.
+
+A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a small interface hiding a large implementation. Deep modules are more testable, more AI-navigable, and let you test at the boundary instead of inside.
+
+## Process
+
+### 1. Explore the codebase
+
+Explore the codebase using your available tools (bash, rg, view, glob, find). Navigate organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small files?
+- Where are modules so shallow that the interface is nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
+- Where do tightly-coupled modules create integration risk in the seams between them?
+- Which parts of the codebase are untested, or hard to test?
+
+The friction you encounter IS the signal.
+
+### 2. Present candidates
+
+Present a numbered list of deepening opportunities. For each candidate, show:
+
+- **Cluster**: Which modules/concepts are involved
+- **Why they're coupled**: Shared types, call patterns, co-ownership of a concept
+- **Dependency category**: See [REFERENCE.md](REFERENCE.md) for the four categories
+- **Test impact**: What existing tests would be replaced by boundary tests
+
+Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"
+
+### 3. User picks a candidate
+
+### 4. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would need to rely on
+- A rough illustrative code sketch to make the constraints concrete — this is not a proposal, just a way to ground the constraints
+
+Show this to the user, then immediately proceed to Step 5. The user reads and thinks about the problem while the sub-agents work in parallel.
+
+### 5. Design multiple interfaces
+
+Design multiple radically different interfaces for the deepened module yourself, cycling through different constraints. For each design, write out the complete interface and evaluate it before moving to the next:
+
+1. **Minimal interface** — aim for 1-3 entry points max. What complexity can you hide behind a small surface area?
+2. **Flexible interface** — support many use cases and extension. How do you make it open for future needs?
+3. **Caller-optimised** — make the most common calling pattern trivial. What does the primary caller look like?
+4. **Ports & adapters** (if cross-boundary deps) — isolate side effects from pure logic.
+
+For each design, output:
+
+1. Interface signature (types, methods, params)
+2. Usage example showing how callers use it
+3. What complexity it hides internally
+4. Dependency strategy (how deps are handled — see [REFERENCE.md](REFERENCE.md))
+5. Trade-offs
+
+The `design-an-interface` skill provides a structured approach for this step — invoke it if you want a guided parallel-design flow with sub-agents.
+
+Present designs sequentially, then compare them in prose.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not just a menu.
+
+### 6. User picks an interface (or accepts recommendation)
+
+### 7. Create refactor bead
+
+Invoke the `create-task` skill, passing:
+- **title**: a concise name for the refactor
+- **description**: the bead body using the template in [REFERENCE.md](REFERENCE.md)
+- **priority**: P2
+
+**Always use `create-task`** — never call `bd create` directly for tasks. `create-task` classifies the bead and expands AFK tasks into pipeline stage children that ralph can execute. Do NOT ask the user to review before creating — just create it and share the bead ID.

package/skills/engineering/tdd/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when building features or fixing bugs — or when you mention "red-green-refactor", want "test-first development", or need "tracer bullet" implementation.
+---
+
+# Test-Driven Development
+
+## When to use
+
+- Building features or fixing bugs where correctness matters.
+- Asked for "test-first", "TDD", "red-green-refactor", or "tracer bullets".
+- Designing complex logic where fast feedback on correctness is valuable.
+
+## When NOT to use
+
+- Prototyping, throwaway code, or exploratory spikes where speed of discovery matters more than correctness.
+- Changes so trivial that tests would duplicate type or lint coverage (rename, pure data shuffle).
+- When the test-to-implementation ratio would be absurdly high — a one-line change requiring extensive test setup.
+- Testing documentation or skill files to prove content exists in markdown. Tests verify executable code, not prose. If you want to validate a SKILL.md structure, use a linter or schema check instead.
+
+## Philosophy / rationale
+
+- **Tests verify behaviour through public interfaces, not implementation details.** Code can change entirely; tests should not. A passing test should survive a refactor that preserves behaviour.
+- **Vertical tracer bullets beat horizontal slice-and-pray.** One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Writing all tests first tests imagined behaviour, not actual behaviour.
+- **RED means you have a specification.** GREEN means it works. REFACTOR means make it read well — run `style-code` to guide the refactoring shape. Each state has a purpose; do not skip or blur them.
+
+## Workflow
+
+### 1. Plan
+
+Before writing any code:
+
+- Confirm with the user what interface changes are needed.
+- Confirm which behaviours to test and prioritise them.
+- Design interfaces for testability.
+- List the behaviours to test (not implementation steps).
+
+You cannot test everything. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behaviour → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet — it proves the path works end-to-end.
+
+### 3. Incremental loop
+
+For each remaining behaviour:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+- One test at a time.
+- Only enough code to pass the current test.
+- Do not anticipate future tests.
+- Keep tests focused on observable behaviour.
+
+### 4. Refactor
+
+After all tests pass, run `style-code` to guide the refactoring shape:
+
+- Extract duplication.
+- Deepen modules — move complexity behind simple interfaces.
+- Apply SOLID principles where natural.
+- Consider what the new code reveals about existing code.
+- Run tests after each refactor step.
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Red Flags
+
+- **Horizontal slicing.** Writing all tests first, then all implementation. You end up testing imagined behaviour, commit to test structure before understanding the implementation, and produce tests that pass when behaviour breaks and fail when it is fine.
+- **Refactoring while RED.** The safety net is not up yet. Get to GREEN before restructuring.
+- **Anticipating future tests.** Writing code you do not need yet because a future test will require it. It nearly always guesses the wrong shape.
+- **Testing implementation details.** Coupling tests to internal structure so they break when you rename a private function or restructure internals. Test the public interface.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+|---|---|
+| "I will write the tests after" | Tests written after code tend to test what the code does, not what it should do. You lose the specification benefit of TDD. |
+| "TDD is slower" | TDD front-loads time but saves debugging time. Net neutral or faster for anything non-trivial. |
+| "This is too simple for TDD" | The simplest changes often have the most hidden assumptions. TDD surfaces them early. |
+| "I already know what the implementation looks like" | Then write the test first to prove it. If the test forces a different interface, the implementation was wrong. |
+
+## Cross-skill references
+
+| When you need… | Use this skill |
+|---|---|
+| Test-writing conventions (assertions, mocking, structure) | `style-tests` |
+| Code-level style and conventions | `style-code` |
+| Domain terminology for test names and module boundaries | `grill-with-docs` |
+
+Reference docs bundled with this skill: `tests.md`, `mocking.md`, `deep-modules.md`, `interface-design.md`, `refactoring.md`.
+
+## Examples
+
+### Horizontal vs vertical slicing
+
+| Horizontal (wrong) | Vertical (right) |
+|---|---|
+| Write test1, test2, test3, test4, test5 | Write test1 → impl1 |
+| Then write impl1, impl2, impl3, impl4, impl5 | Then test2 → impl2 |
+| Tests test imagined behaviour, not actual | Each test responds to what you just learned |
+
+### Test that survives refactor vs one that does not
+
+| Instead of… | Write… |
+|---|---|
+| Mocking an internal method and asserting it was called | Calling the public API and asserting on the result |
+| Testing that a private helper returns an intermediate value | Testing that the public function returns the correct output |
+
+## Phase-gate checklists
+
+### Phase 1: Planning complete
+
+- [ ] User approved the interface and prioritised behaviours
+- [ ] Behaviours are listed in terms of observable outcomes, not implementation steps
+
+### Phase 2: Tracer bullet done
+
+- [ ] End-to-end path proven through the public API
+- [ ] Test passes GREEN with minimal implementation
+
+### Phase 3: Incremental loop complete
+
+- [ ] All prioritised behaviours tested
+- [ ] All tests GREEN
+
+### Phase 4: Refactor complete
+
+- [ ] Duplication extracted without changing behaviour
+- [ ] All tests still GREEN after every refactor step
+
+## Verification checklist
+
+- [ ] Test describes behaviour, not implementation
+- [ ] Test uses public interface only
+- [ ] Test would survive internal refactor
+- [ ] Code is minimal for this test
+- [ ] No speculative features added
+- [ ] Never refactored while RED

package/skills/engineering/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/skills/engineering/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/skills/engineering/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/skills/engineering/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/skills/engineering/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/skills/engineering/technical-direction/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: technical-direction
+description: Drive collaborative technical design by challenging assumptions, mapping constraints, comparing alternatives, and producing a justified recommendation. Use when user wants to decide technical direction after PRD, evaluate architecture/technology choices, or asks to design a solution with tradeoff analysis.
+---
+
+# Technical Direction
+
+Act like a pragmatic, challenging staff engineer: constructive, direct, evidence-driven.
+
+## Workflow
+
+1. **Anchor on problem context**
+   - Start from PRD or user brief
+   - Confirm technical goals, non-goals, and decision horizon
+
+2. **Discover constraints from codebase first**
+   - Investigate architecture, existing interfaces, deployment/runtime constraints, data model boundaries, and team conventions
+   - Note unknowns and risks
+
+3. **Challenge loop (one question at a time)**
+   - Ask focused, high-leverage questions
+   - Challenge vague claims and hidden assumptions
+   - Require explicit justification for each major decision
+   - Keep drilling until constraints and tradeoffs are concrete
+
+4. **Generate options**
+   - Always include Option A (extend current approach), Option B (moderate architectural shift), and Option C (stronger alternative using new tech/pattern)
+   - For each option: feasibility, complexity, migration cost, operational impact, testability, performance, and failure modes
+
+5. **Use web research when needed**
+   - Do this autonomously when codebase evidence is insufficient or a high-impact decision needs external comparison
+   - Prefer authoritative sources (official docs, maintainers, widely adopted production guidance)
+   - Bring findings back as tradeoffs, and retain source links as references
+
+6. **Converge on a recommendation**
+   - Select the best-fit option for current constraints
+   - Explicitly explain why alternatives were not chosen
+   - List decision triggers that would justify revisiting later
+
+7. **Write decision memo**
+   - Ensure `docs/technical-direction/` exists
+   - Save to `docs/technical-direction/<feature-slug>.md` using this template:
+
+```md
+# Technical Direction: <Feature Name>
+## Problem and target outcome
+- What we are solving
+- Why this matters now
+## Current-state constraints
+- Architecture and integration constraints
+- Team/runtime/operational constraints
+- Unknowns and assumptions
+## Options considered
+### Option A: <name>
+- Approach
+- Pros
+- Cons
+- Risks
+### Option B: <name>
+...
+### Option C: <name>
+...
+## Recommendation
+- Chosen approach
+- Why this is best under current constraints
+- Why alternatives were not selected
+## Tradeoffs accepted
+- Explicit compromises and consequences
+## Validation plan
+- Fastest experiments/spikes to de-risk decision
+- Success/failure signals
+## Revisit triggers
+- Conditions that should force re-evaluation
+## References
+- Web sources used for decisions (title + URL)
+- Code evidence links (repo path + line range, and permalink URL when available)
+```
+
+## Rules
+
+- Ask questions one at a time.
+- If the answer exists in the codebase, investigate before asking.
+- Be challenging but collaborative; do not optimize for agreement.
+- Avoid premature implementation details until direction is selected.
+- Every recommendation must include explicit constraints and tradeoffs.
+- When web or code sources materially inform decisions, include them in `## References`.

package/skills/planning/classify-bead/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: classify-bead
+description: Classify a bead as AFK or HITL and apply the implementation-type label. Use when a bead is missing its implementation-type label, when picking up a bead to work on, or when any skill creates a new bead.
+---
+
+# Classify Bead
+
+Determine whether a bead requires human action (HITL) or can be completed autonomously by an agent (AFK), then persist the result as a label.
+
+## When to use
+
+- When picking up a bead that is missing the `implementation-type` label.
+- Immediately after creating a new bead, before claiming or scheduling it.
+- Any time you are unsure of a bead's classification.
+
+## Invocation
+
+**Always run this skill as a subagent** (background `general-purpose` agent, `model: haiku`) to avoid loading bead content into the calling agent's context. Classification is a rubric lookup, not code generation, so the smaller/cheaper model is sufficient. Pass the bead ID and the `bd prime` output. The subagent runs the procedure below and reports back the classification and the `bd tag` command it applied.
+
+Only run inline (without a subagent) if no task-spawning capability is available in the current environment.
+
+**Callers should check `bd label list <id>` themselves first.** If `implementation-type` is already present, skip spawning this skill entirely — spawning a subagent purely to re-read a label that's already there wastes a full agent call.
+
+## Procedure
+
+### 1. Check for an existing label
+
+```bash
+bd label list <id>
+```
+
+- If `implementation-type:afk` is present → classification is **AFK**. Stop here.
+- If `implementation-type:hitl` is present → classification is **HITL**. Stop here.
+
+### 2. Check the `## Type` field (back-compat)
+
+```bash
+bd show <id>
+```
+
+Locate the `## Type` section in the bead body.
+
+- If the value is `HITL` (case-insensitive) → classification is **HITL**. Proceed to step 4.
+- If the value is `AFK` (case-insensitive) → classification is **AFK**. Proceed to step 4.
+
+### 3. Classify from first principles
+
+If neither the label nor the `## Type` field is present, read the full bead body and apply this rubric:
+
+**HITL** — the bead requires a human if at least one of the following is true:
+- The outcome cannot be verified by an agent (e.g. visual review, stakeholder sign-off, UX judgement call).
+- The work requires a manual action only a human can perform (e.g. credential setup, secrets management, external service configuration, infrastructure provisioning outside the codebase).
+- A decision must be made that the agent cannot make unilaterally (e.g. architectural choice between equally valid options, regulatory or legal sign-off).
+
+**AFK** — the agent can implement, verify, and complete the task autonomously, and all acceptance criteria are machine-checkable.
+
+Prefer AFK. Do not classify as HITL just because the task is complex — only when the agent genuinely cannot complete or verify it without human involvement.
+
+### 4. Apply the label
+
+```bash
+bd tag <id> implementation-type:afk    # or implementation-type:hitl
+```
+
+### 5. Return the classification
+
+Report back `AFK` or `HITL` so the calling skill or agent can act on it.