cue-ai 0.9.0 → 0.9.2

package/resources/skills/skills/meta/cue-developer/references/architecture.md

@@ -0,0 +1,65 @@
+# Internals
+
+Read this before changing the resolver or materializer; they are the hot path
+every `claude` / `codex` launch runs through.
+
+## Launch hot path
+
+```
+claude (shim) -> cue launch claude
+  -> resolveProfileForCwd()    # find which profile applies to cwd
+  -> loadProfile()             # YAML parse + inheritance chain
+  -> materializeRuntime()      # hash check, then symlink skills + write settings
+  -> exec(real claude binary)  # hand off to the real agent
+```
+
+The materializer is content-addressed: if the profile has not changed, launch
+is a stat plus a sha256 compare (under ~5ms overhead). Keep this path
+allocation-light and avoid adding synchronous network or heavy parsing to it.
+
+## Profile resolution order
+
+1. `--cue-profile X` flag (explicit).
+2. `.cue-profile` file in cwd, walking up to `$HOME`.
+3. Repo-level default (`.cue-profile` at the git root).
+4. Global default (`~/.config/cue/default-profile`).
+5. TUI picker (interactive fallback).
+
+## Key modules
+
+| Module | Purpose |
+|---|---|
+| `cwd-resolver.ts` | Find which profile applies to the current directory |
+| `profile-loader.ts` | Parse YAML, resolve inheritance chains |
+| `runtime-materializer.ts` | Build isolated config dirs with symlinked skills |
+| `resolver-local.ts` | Find skills on disk by slug |
+| `resolver-npx.ts` | Fetch and cache skills from GitHub repos |
+| `skill-linter.ts` | Validate SKILL.md against R001-R008 |
+| `manifest-cache.ts` | Cache resolved profiles for fast repeat launches |
+
+## Runtime layout
+
+Materialized runtimes live under `~/.config/cue/runtime/<profile>/`. They are
+generated, never hand-edited. To inspect what a launch would produce without
+running it:
+
+```bash
+cue launch claude --dry-run
+```
+
+## Where things live
+
+- CLI source: `src/` (commands in `src/commands/`, shared libs in `src/lib/`).
+- Profiles: `profiles/<name>/profile.yaml`.
+- Skill library: `resources/skills/skills/<category>/<slug>/`.
+- MCP configs: `resources/mcps/`.
+- Claude Code plugin (slash commands): `plugins/cue/`.
+- cue studio dashboard: `web/` (React + Vite, own tsconfig).
+
+## CI gate reality
+
+CI on `main` can show red on validate or e2e jobs that depend on private or
+local-only MCP references. Those are a known baseline condition, not your
+break. The real gates for a change are `lint` and `test`. Before merging, prove
+your change adds no new failing checks relative to the base branch rather than
+chasing a pre-existing red job.

package/resources/skills/skills/meta/cue-developer/references/build_and_test.md

@@ -0,0 +1,72 @@
+# Build & Test
+
+cue runs its TypeScript directly under Bun, so local development has no compile
+step. A build only happens when packaging for npm distribution.
+
+## Running cue locally
+
+```bash
+bun src/index.ts <command> [args...]
+
+# Examples
+bun src/index.ts status
+bun src/index.ts list
+bun src/index.ts validate --all
+bun src/index.ts doctor
+bun src/index.ts launch claude --dry-run
+```
+
+## Tests
+
+```bash
+bun test                              # whole suite
+bun test src/lib/skill-router.test.ts # one file
+bun test --filter "loadProfile"       # tests matching a pattern
+```
+
+Tests live next to their source (`foo.ts` and `foo.test.ts`) and use Bun's
+built-in runner. New commands and library functions require tests.
+
+## Typecheck and lint
+
+```bash
+bunx tsc --noEmit       # typecheck the root project
+bunx biome lint src     # lint the source tree
+```
+
+The web studio (under `web/`) has its own `tsconfig.json`; typecheck it from
+inside that directory:
+
+```bash
+cd web && bunx tsc --noEmit
+```
+
+## Skill linting
+
+Any SKILL.md you touch must pass the linter with zero errors:
+
+```bash
+cue lint-skill resources/skills/skills/<category>/<slug>/SKILL.md
+cue lint-skill <path> --fix     # auto-fix the fixable warnings
+```
+
+`cue lint-skill` exits 0 when there are no errors (warnings and info are
+allowed but lower the score). The Stop-time quality gate
+(`resources/quality-gates/lint-skill-pass.sh`) blocks if any changed SKILL.md
+has a lint error.
+
+## Packaging build (rare)
+
+```bash
+bun run build:bundle     # node-targeted dist/cue.js for npm publish
+```
+
+You do not need this for normal development. If the local CLI behaves oddly
+after pulling, the cause is almost never a stale build (there is none); re-run
+`bun install` and `bun test`.
+
+## RAM-constrained machines
+
+cue's test suite is light compared to a CUDA build, so there is no
+`PARALLEL_LEVEL` knob to tune. If `bun test` is slow, run a single file or a
+`--filter` pattern while iterating, then the full suite once before committing.

package/resources/skills/skills/meta/cue-developer/references/contributing.md

@@ -0,0 +1,75 @@
+# Contributing: Commits, PRs, Common Tasks
+
+## Pull request rules
+
+1. **One concern per PR.** Do not mix a feature with a refactor.
+2. **Tests required** for new commands and library functions.
+3. **`bun test` green** before submitting; all tests must pass.
+4. **Keep the README updated** if you add a user-facing feature.
+5. **Profile changes** run `cue validate --all` before the PR.
+
+## Commit messages
+
+Conventional Commits: `type(scope): summary`. Types: `feat`, `fix`, `refactor`,
+`docs`, `test`, `chore`, `perf`, `ci`. Keep the subject intent-first; add a body
+only when the why is non-obvious. Example:
+
+```
+fix(list): render empty skill list instead of throwing
+```
+
+## The gated ship flow
+
+Landing completed work is pre-authorized in this repo through a gated flow:
+commit, open the PR, run an AI review, and merge only when both hold:
+
+- **Review clean.** No CRITICAL or HIGH finding.
+- **No new failures vs base.** The change adds zero failing checks relative to
+  the base branch. On a repo with green CI that means green CI.
+
+If a CRITICAL/HIGH finding appears, or a new check fails, stop and report. Do
+not merge past the gate.
+
+Still hard stops, never do these: `git push --force`, committing directly on a
+protected base, bundling unrelated working-tree changes into the PR, or merging
+past a failing gate.
+
+## Draft-PR rule for agents
+
+When an automated agent opens a PR, open it as a draft until a human or the AI
+review has looked at it. Keep PR descriptions short: what changed and why. Skip
+"how it works" walkthroughs and file-by-file tables; the diff already shows
+those.
+
+## Common-task recipes
+
+### Add a CLI command
+
+1. Create `src/commands/my-command.ts` exporting `run(args: string[]): Promise<number>`.
+2. Register it in `src/commands/_index.ts`.
+3. Add `src/commands/my-command.test.ts`.
+4. `bun test` and `bunx tsc --noEmit`.
+
+### Add a dependency
+
+cue keeps a small dependency tree. Confirm the need first, then propose the
+`package.json` edit with a one-line rationale and let the maintainer run
+`bun add <pkg>`. Never run a global install.
+
+### Add a profile
+
+```bash
+cue new <name>          # scaffold profiles/<name>/
+# edit profiles/<name>/profile.yaml
+cue validate <name>     # or: cue validate --all
+```
+
+### Add a skill or MCP
+
+See [skill_and_mcp_authoring.md](skill_and_mcp_authoring.md).
+
+## Script and workflow authoring
+
+Extend an existing script or CI file before adding a new one. Avoid speculative
+flags, restated defaults, and silent fallbacks; fail loud with a clear message
+when an assumption breaks.

package/resources/skills/skills/meta/cue-developer/references/conventions.md

@@ -0,0 +1,57 @@
+# Coding Conventions
+
+Match the file you are editing. When a local pattern conflicts with this list,
+the local pattern wins; raise the conflict instead of silently diverging.
+
+## Language and modules
+
+- TypeScript, ESM (`import` / `export`), no CommonJS `require`.
+- Lazy-import heavy modules inside command handlers so cold start stays fast
+  (see existing files in `src/commands/`).
+- Prefer `node:fs/promises` for async work; use `node:fs` sync only in hot
+  paths like the launch resolver.
+
+## Naming
+
+- Variables and functions: `camelCase`, descriptive.
+- Booleans: `is`, `has`, `should`, or `can` prefix.
+- Types, interfaces, classes: `PascalCase`.
+- Constants: `UPPER_SNAKE_CASE`.
+
+## File organization
+
+- Many small files over few large ones. High cohesion, low coupling.
+- One command per file in `src/commands/`, registered in `_index.ts`.
+- Tests sit next to source: `foo.ts` and `foo.test.ts`.
+- Aim for under 400 lines per file; 800 is the hard ceiling.
+
+## Error handling
+
+- Use typed error classes for failures the caller should branch on (see
+  `resolver-npx.ts` for the pattern).
+- Handle errors explicitly. Do not swallow them silently.
+- User-facing CLI messages should be short and actionable; log detail to stderr.
+
+## Immutability
+
+- Build new objects instead of mutating inputs. Return a changed copy rather
+  than editing in place. This keeps the resolver and materializer predictable.
+
+## Input validation
+
+- Validate at the boundary: CLI args, parsed YAML, file contents, network
+  responses. Fail fast with a clear message.
+
+## Tests
+
+- New commands and library functions need tests.
+- Arrange, Act, Assert structure. Name the test for the behavior under test, for
+  example `returns empty array when no profile matches`.
+- Keep tests isolated; do not let one test's environment variables leak into
+  another (a past suite failure came from exactly this).
+
+## Voice for docs and skills
+
+No em dashes. Avoid filler and AI-vocabulary words (delve, crucial, robust,
+comprehensive, nuanced, leverage, furthermore, moreover, pivotal, landscape).
+Lead a sentence with the verb or the answer.

package/resources/skills/skills/meta/cue-developer/references/first_time_setup.md

@@ -0,0 +1,51 @@
+# First-Time Dev Environment Setup
+
+The clone, install, first-run, first-test walkthrough for a fresh cue checkout.
+
+## Questions to ask up front
+
+- Is `bun` installed and at least version 1.0? (`bun --version`)
+- Is this a fork (for contribution) or the upstream clone (for local change)?
+- Which branch? Default `main`. A release branch may exist: `git branch -r | grep release`.
+
+## Steps
+
+```bash
+# 1. Clone
+git clone https://github.com/opencue/cuecards.git ~/Documents/cue
+cd ~/Documents/cue
+
+# 2. Install deps (requires bun >= 1.0)
+bun install
+
+# 3. Run cue locally (no build step, bun runs the TypeScript)
+bun src/index.ts status
+bun src/index.ts list
+
+# 4. Run the test suite
+bun test
+```
+
+A green `bun test` means the environment is ready. If install fails, confirm `bun --version` is >= 1.0; cue does not use npm, conda, or a virtualenv.
+
+## Prerequisites
+
+- **Bun** >= 1.0 from [bun.sh](https://bun.sh)
+- **Git** for cloning and version control
+- **Node.js** >= 20 (optional, only for npm-based MCPs)
+
+## What NOT to do
+
+- Do not `npm install` or `pip install` anything. cue is bun-only.
+- Do not run a global install. If a dependency is genuinely missing, it belongs in `package.json` via `bun add`, after discussion.
+- Do not edit files outside the repo to make the build work.
+
+## Verifying the install
+
+```bash
+bun src/index.ts --version     # prints the cue version
+bun src/index.ts doctor        # environment health check
+bun test                       # full suite, must be green before you start
+```
+
+If `cue` (the installed shim) is also on PATH, `cue lint-skill` and other subcommands work without the `bun src/index.ts` prefix.

package/resources/skills/skills/meta/cue-developer/references/skill_and_mcp_authoring.md

@@ -0,0 +1,84 @@
+# Skill & MCP Authoring
+
+Adding or improving a skill or MCP is the most common cue contribution. Get the
+trigger and the lint gate right and the rest follows.
+
+## Where skills live
+
+```
+resources/skills/skills/<category>/<slug>/
+  SKILL.md          # the skill itself (frontmatter + body)
+  references/       # progressive-disclosure docs, loaded on demand
+  evals/evals.json  # optional activation eval scenarios
+```
+
+Categories already in use include `meta`, `gstack`, `tools`, `research`,
+`review`, `medusa`, and others. Put a cue-about-cue skill under `meta/`.
+
+## Scaffold a new skill
+
+```bash
+cue skills-new <name>
+# then edit resources/skills/skills/<category>/<name>/SKILL.md
+```
+
+The resolver auto-discovers the skill once the file exists; no registration
+step.
+
+## The description is the trigger
+
+The `description:` field is what makes Claude activate the skill. Write it as
+"Use when the user says X, Y, or Z" with concrete quoted phrases. A skill with a
+vague description does not fire. Examples lift activation from about 50% to
+about 90%, so include one.
+
+Rules the linter enforces (R001-R008, zero errors required to pass):
+
+- **R001 (error):** frontmatter must have `name:`.
+- **R002 (error):** frontmatter must have `description:`.
+- **R003 (warning):** `description` should be 200 characters or fewer.
+- **R004 (warning):** the description needs a trigger phrase ("Use when ...").
+- **R005 (error):** `allowed-tools` must use Anthropic's `Bash(name:*)` /
+  `Read(path)` form.
+- **R006 (warning):** if the skill declares CLI dependencies, add a
+  `## Prerequisites` section.
+- **R007 (info):** add `category:` and `tags:` for discoverability.
+- **R008 (warning):** no broken in-document anchor links.
+
+Voice (R009) bans em dashes and AI-vocabulary words. Use commas and periods.
+
+## The references/ convention
+
+Push detail out of SKILL.md into `references/*.md` and link to it. This keeps
+the skill short (aim under 200 lines) while making the depth available on
+demand. cue's dominant convention is a folder named `references/` (not
+`resources/`). Link with relative paths, for example
+`[build & test](references/build_and_test.md)`.
+
+## Validate before you finish
+
+```bash
+cue lint-skill resources/skills/skills/<category>/<slug>/SKILL.md
+cue lint-skill <path> --fix     # auto-fix fixable warnings
+```
+
+Zero errors is the bar. Aim to clear the easy warnings too (trigger phrase,
+tags, an example) for a high score. Never wire an unlinted skill into a profile.
+
+## Adding an MCP
+
+MCP server configs live under `resources/mcps/`. Match the shape of an existing
+config in that directory. After adding one, validate any profile that
+references it with `cue validate <profile>`.
+
+## Overlap check
+
+Before writing a new skill, search for an existing one that already covers the
+job:
+
+```bash
+grep -ril "<keyword>" resources/skills/skills --include=SKILL.md
+```
+
+If a skill is close, improve it instead of adding a near-duplicate. Overlap
+splits activation and confuses discovery.

package/resources/skills/skills/meta/cue-developer/references/troubleshooting.md

@@ -0,0 +1,42 @@
+# Troubleshooting
+
+## Build and run
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `bun: command not found` | Bun not installed or not on PATH | Install from [bun.sh](https://bun.sh), open a fresh shell |
+| Commands fail right after `git pull` | Stale `node_modules` | Re-run `bun install`; there is no compiled artifact to clear |
+| `cue` (shim) runs old behavior | Shim points at a different checkout | Run `bun src/index.ts <cmd>` directly to confirm, then re-check the shim path |
+| TypeScript errors only in `web/` | Wrong tsconfig scope | `cd web && bunx tsc --noEmit` |
+
+## Tests
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| One test passes alone but fails in the suite | Env-var or state leak across tests | Isolate setup/teardown; do not let one test mutate global env for another |
+| A profile test fails after editing `profiles/` | Profile no longer validates | `cue validate --all` and fix the reported field |
+| Flaky failure | Order dependence or a real race | Re-run the single file; if it still flakes, treat it as a real bug, not noise |
+
+## Lint gate
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `cue lint-skill` reports an error | R001/R002/R005 (missing name, missing description, malformed `allowed-tools`) | Fix the frontmatter; `--fix` handles the auto-fixable warnings |
+| Stop-time gate blocks the session | A changed SKILL.md has a lint error | `cue lint-skill <path>` to see it, fix, re-run |
+| Broken-anchor warning (R008) | A `#anchor` link points at a heading that does not exist | Fix or remove the anchor; relative file links to real files are fine |
+| Em-dash warning (R009) | An em dash in prose | Replace with commas or periods, or wrap a legitimate use in backticks |
+
+## Dependencies
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| CI flags a dependency mismatch | `package.json` and lockfile drifted | `bun install` to regenerate the lockfile, commit it |
+| Tempted to add a package | A utility feels missing | Confirm the need, propose the `package.json` edit, let the maintainer `bun add` it; never global-install |
+
+## When stuck
+
+- `cue doctor` for an environment health check.
+- `cue launch claude --dry-run` to see what a launch would materialize.
+- Read the neighboring source and its test before changing behavior.
+- After three failed attempts at the same fix, stop and re-state the problem
+  rather than flailing; the approach is probably wrong.

package/resources/skills/skills/meta/delegation-check/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: delegation-check
+description: 'Lint that Agent()/subagent_type delegation prompts do not conflict with or duplicate the spawned agent role. Use when the user says "check delegation" or "delegation conflict".'
+tags: [meta, cue, skills, delegation, quality]
+category: meta
+version: 1.0.0
+---
+
+# Delegation Check
+
+Check that delegation prompts and agent role definitions respect content
+ownership. When a skill spawns an agent (`Agent(...)`, legacy `Task(...)`, or a
+`subagent_type` dispatch), the prompt should state WHAT to do this run while the
+agent file states WHO it is and HOW it works. This skill finds where the two
+fight or repeat each other, across 7 conflict dimensions.
+
+Ported from the CCW `delegation-check` skill. The algorithm is preserved. The
+CCW machinery (`ccw` CLI, Gemini evaluator, `.workflow/` paths, `ccw-tools` MCP)
+is dropped in favor of Read, Grep, Glob, Bash, and an optional `Agent` pass.
+
+## When to activate
+
+- User says "check delegation", "delegation conflict", "prompt vs role check"
+- User says "audit my Agent() calls" or "do my prompts fight the agent"
+- User is reviewing a skill that spawns a `subagent_type` and wants it clean
+- Proactively, when writing or reviewing a skill that dispatches an agent
+
+## The 7 dimensions
+
+| # | Dimension | The bad smell |
+|---|---|---|
+| D1 | Role re-definition | Prompt says "You are a..." that the agent already owns |
+| D2 | Domain expertise leak | Decision tables, heuristics, good/bad examples in the prompt |
+| D3 | Quality gate duplication | Same self-check in both, or a contradictory limit |
+| D4 | Output format conflict | Prompt routes on markers the agent never emits |
+| D5 | Process override | Prompt dictates step-by-step HOW, not just WHAT |
+| D6 | Scope authority conflict | Prompt picks the library or pattern the agent should pick |
+| D7 | Missing contracts | No return contract, or a spawn of an agent that does not exist |
+
+Full rule text, exceptions, and severities live in
+[specs/separation-rules.md](specs/separation-rules.md). Read it before judging,
+the exceptions matter (mode references, cross-cutting policy, user-decision
+passthrough are not violations).
+
+## Steps
+
+### Step 1 - Set scope
+
+Map the user's request to a scope: one skill, one command-agent pair, a
+directory, or a full scan. If it is unclear, ask with `AskUserQuestion`. Scope
+rules are in [specs/scan-algorithm.md](specs/scan-algorithm.md).
+
+### Step 2 - Find the spawn sites
+
+Grep the in-scope files for spawn patterns.
+
+```bash
+grep -rn 'Agent(\|Task(\|subagent_type' "$SCOPE"
+```
+
+For each hit, pull the `subagent_type`, the full prompt string, and its line
+range.
+
+### Step 3 - Locate the agent
+
+For each named agent, look in the standard spots.
+
+```bash
+ls .claude/agents/${AGENT}.md resources/skills/skills/*/agents/${AGENT}.md 2>/dev/null
+```
+
+No file and the type is not `general-purpose` means a `MISSING_AGENT` finding,
+which is a D7 error. A `general-purpose` spawn has no agent file, so judge D1 to
+D6 against the inline role text in the prompt itself.
+
+### Step 4 - Parse both sides
+
+Parse the prompt for intent blocks and anti-patterns. Parse the agent for
+identity, return contract, self-check, and domain sections. Field lists are in
+[specs/scan-algorithm.md](specs/scan-algorithm.md).
+
+### Step 5 - Run D1 to D7
+
+Score each dimension PASS / WARN / ERROR per pair, with a one-line detail. Apply
+the exceptions so legit patterns do not get flagged.
+
+### Step 6 - Report
+
+Show a per-pair table, a verdict (CLEAN / REVIEW / CONFLICT), and a ranked fix
+list. Each fix names the file and line, what is wrong, and which owner the
+content moves to.
+
+## Example
+
+Input: "check delegation on resources/skills/skills/gstack/ship/SKILL.md"
+
+The scan finds a `subagent_type: "general-purpose"` dispatch at the coverage-audit
+step. Output:
+
+```
+DELEGATION-CHECK > SCAN COMPLETE
+
+Scope: gstack/ship/SKILL.md
+Pairs checked: 1 (ship -> general-purpose coverage audit)
+Findings: 0 errors, 1 warning, 0 info
+Verdict: CLEAN
+
+| Pair | D1 | D2 | D3 | D4 | D5 | D6 | D7 |
+|------|----|----|----|----|----|----|----|
+| ship -> general-purpose | ok | ok | ok | warn | ok | ok | ok |
+
+Fix priority:
+1. D4 (line 590): prompt says "report the conclusion" but states no return
+   marker the parent routes on. Add an explicit "Return `## COVERAGE OK` or
+   `## GAPS FOUND`" so /ship can branch on the result.
+```
+
+A second example, a conflict:
+
+Input: a skill spawns `subagent_type: "plan-checker"` with a prompt that opens
+`You are a code quality expert. Always prefer 2-3 task plans.`
+
+Output flags D1 (error: prompt redefines the agent identity that
+`.claude/agents/plan-checker.md` already owns) and D2 (error: the "2-3 task"
+heuristic belongs in the agent's domain section, not the prompt). Verdict:
+CONFLICT. Fix: strip both lines from the prompt, keep them in the agent file.
+
+## Rules
+
+- Read [specs/separation-rules.md](specs/separation-rules.md) before scoring. The
+  exceptions stop false positives.
+- A `general-purpose` spawn with inline role text is the cue norm, not a D1
+  violation. Judge it against itself.
+- Passing through a user-locked decision from a context file is correct (D6
+  info), not a scope conflict. Do not flag it.
+- A cross-cutting policy block applied to every spawn uniformly is `info`, not an
+  error, unless it copies an agent domain section word for word.
+- Never auto-edit the skill or agent. Report findings and a fix, let the user
+  apply it.
+- Cite file and line for every error and warning, no vague verdicts.
+
+## What this skill does NOT do
+
+- Run or test the agents. It reads the prompt and the role, not the runtime.
+- Score skill quality or activation. Use `meta/skill-reviewer` for that.
+- Optimize a description field. Use `meta/description-optimizer`.
+- Find or wire MCP servers. Use `meta/mcp-finder`.
+- Edit files. It is read-only, it outputs findings and fixes.