@causyne/agent 0.0.0-stage → 1.10.1

package/LICENSE

@@ -0,0 +1,102 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Ikbal Fadilah
+
+Licensed Work:        Causyne Agent 1.10.1
+                      The Licensed Work is (c) 2026 Ikbal Fadilah.
+
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you do not use the Licensed Work for a Commercial
+                      Offering that competes with any offering of the Licensor
+                      or its affiliates that includes the Licensed Work.
+
+                      A "Commercial Offering" is a product or service offered
+                      to third parties on a paid basis (including through paid
+                      subscriptions or usage-based pricing) that provides
+                      AI agent, AI automation, or AI-assisted development
+                      capabilities substantially similar to the Licensed Work.
+
+                      Personal, educational, and internal non-commercial use
+                      is always permitted.
+
+Change Date:          2030-08-09
+
+Change License:       Apache License, Version 2.0
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# Causyne Agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Development status:** Causyne Agent is under active development. It is not
+> yet a stable release, and its interfaces and behavior may change.
+
+Causyne Agent is an AI agent harness for complex, multi-step work. It is being
+developed to turn intention into meaningful progress through capable,
+increasingly autonomous AI, with clear boundaries and human control.
+
+This repository is an early source-available development snapshot. Public
+documentation is intentionally concise while the project is evolving.
+
+Learn more at [causyne.com](https://causyne.com/).
+
+## Development
+
+Node.js 24 or newer is required.
+
+```sh
+npm ci --ignore-scripts
+npm test
+npm run typecheck:strict
+npm run check:public
+```
+
+Please read [SECURITY.md](SECURITY.md) before running development builds or
+reporting a security concern. Never commit API keys, credentials, private
+configuration, or personal data.
+
+The source is available under the [Business Source License 1.1](LICENSE).
+Causyne Agent is source-available software and is not presented as OSI-approved
+open-source software.

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security
+
+Causyne Agent is under active development and has not reached a stable security
+baseline. Development builds may execute tools that interact with files,
+processes, applications, and external model providers. Review requested actions
+and use an isolated workspace when evaluating the project.
+
+## Protecting credentials
+
+- Keep API keys and provider credentials outside the repository.
+- Do not commit `.env` files, private keys, authentication tokens, personal
+  configuration, or generated state.
+- Use test credentials with minimal permissions during development.
+- Revoke and rotate any credential that is accidentally disclosed.
+
+The release checks scan for common credential formats, but automated scanning
+cannot prove that a repository contains no secrets.
+
+## Reporting a vulnerability
+
+Please avoid publishing exploit details in a public issue. Use the repository's
+private security-reporting channel when it becomes available. Until that channel
+is published, retain the report privately rather than exposing user data or a
+working exploit.

package/bin/causyne.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Execute the readable modules reviewers receive in the package.
+if (Number(process.versions.node.split('.')[0]) < 24) {
+  console.error('Causyne Agent requires Node.js 24 or newer.');
+  process.exit(1);
+}
+try {
+  await import('../src/entrypoint.js');
+} catch (error) {
+  if (process.stdout.isTTY) process.stdout.write('\x1b[?1006l\x1b[?1000l\x1b[?2004l\x1b[?25h');
+  console.error('Causyne Agent failed:', error);
+  process.exitCode = 1;
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,63 @@
+# Current architecture
+
+Decision: 2026-10-19. Causyne Agent is an independent local desktop CLI.
+
+```text
+local terminal -> entrypoint -> cliMode / local approval UI
+                                  |
+                              agentLoop
+                                  |
+              provider adapters <-> plan / act / observe / reflect
+                                  |
+             policy + workspace checks + approvals + tool registry
+                                  |
+                 local processes / files / desktop applications
+                                  |
+                  observations, memory, sessions, checkpoints
+```
+
+The LLM may be a configured remote API or a local model endpoint. Web tools
+and third-party MCP servers may use the network. Neither makes the program
+a phone-controlled daemon, nor makes every workflow offline. Provider keys
+are stored locally and sent to the chosen provider for authentication.
+
+`LocalCLIConnection` is a local rendering/event adapter, not an inbound network
+connection. `emitEvent` feeds the terminal. Tools can execute host commands;
+the harness is not an OS isolation boundary. Autonomy modes and sandbox rules
+are application policies and require adversarial review.
+
+## Modules
+
+| Concern | Source |
+| --- | --- |
+| Invocation and local session | `entrypoint.js`, `cliMode.js`, `tui/` |
+| Orchestration and budgets | `agentLoop.js`, `modelRouter.js`, `tokenTracker.js` |
+| Host execution | `tools/registry.js`, `sandbox.js`, `execSafe.js` |
+| Models | `providers/`, `modelCatalogue.js` |
+| Context and memory | `memory.js`, `memoryManager.js`, `contextManager.js`, `cortex/` |
+| Recovery | `checkpoints.js`, `gitSnapshot.js`, `sessionStore.js` |
+| Extensions | `mcpClient.js`, `skillsManager.js`, `toolPacks.js`, user skills and Tool Forge |
+| Readable interpreter source | `src/tool-scripts/` |
+
+The current implementation remains JavaScript/ESM on Node.js 24+. The accepted
+language direction is incremental strict TypeScript. Runtime validation is
+still needed at model, filesystem, subprocess and extension boundaries.
+Rust is a possible narrow native worker later; no Rust rewrite is underway.
+
+## Removed boundaries
+
+No active pairing, relay, WebRTC/P2P, mobile command surface, background daemon
+lifecycle, V8 bytecode loader or Android import. Socket editor clients have no
+active network implementation; their methods report held status or use CLI
+fallbacks. Local process automation without an inbound command server remains.
+
+Remote capability is on hold. Its old architecture is retired permanently.
+Future GUI and remote work need distinct decisions and threat models.
+
+## Distribution
+
+The launcher imports the shipped source directly. `npm run build` regenerates
+readable skill data only. No minifier, bytecode compiler or self-updater runs.
+An npm allowlist includes source and security/provenance documents; private
+archives live outside this repository. The unpublished manifest is private.
+The independent repository does not import the Android repository history.

package/docs/PROVENANCE.md

@@ -0,0 +1,29 @@
+# Project provenance
+
+Causyne Agent is the renamed continuation of **Vanexa Agent**. It is not
+presented as an unrelated project or as a way to bypass
+security classification. Version 1.10.0 was the first published local-source
+migration successor to the 1.9.20 working tree.
+
+The previous npm identities were `@ikbal_fadilah_vanexa01/vanexa-agent` and
+`@vanexalabs-ai/vanexa-agent`. The dispute at
+[OpenSSF issue 1470](https://github.com/ossf/malicious-packages/issues/1470)
+references MAL-2026-13364 and MAL-2026-13397. The issue remained open on
+2026-10-19, but the advisory files have different current states:
+MAL-2026-13397 is marked withdrawn and was moved to OpenSSF's `osv/withdrawn`
+tree in merged pull request 1473; MAL-2026-13364 remained in `osv/malicious`.
+Withdrawal of one record does not resolve the other. See
+`docs/SECURITY_REVIEW.md` for package-specific evidence and links.
+
+Historical remote-control sources, private operating documents, and unrelated
+application code are excluded from this project. The repository begins with the
+independent local CLI source rather than importing the unrelated application
+history.
+
+Current architecture changes do not prove historical packages harmless. A source
+hash or a deterministic intermediate bundle also does not prove that an old
+distributed V8 artifact is equivalent to source. Earlier reproducibility claims
+must be checked against actual versioned artifacts before repeating them.
+
+Do not republish old binaries as a Causyne release. Keep version-specific
+evidence and clearly distinguish remediation from requests to correct history.

package/docs/SECURITY_REVIEW.md

@@ -0,0 +1,89 @@
+# Security review and migration status
+
+Review date: 2026-10-19. This is a scoped source and package review, not a
+claim that Causyne Agent is free from vulnerabilities.
+
+## OpenSSF records
+
+The legacy packages have two distinct OpenSSF records:
+
+- `MAL-2026-13397` names `@vanexalabs-ai/vanexa-agent` versions 1.3.50 through
+  1.3.62. OpenSSF's current record marks this advisory **withdrawn** as of
+  2026-08-25, and the repository moved it from `osv/malicious` to
+  `osv/withdrawn` in merged pull request 1473.
+- `MAL-2026-13364` names `@ikbal_fadilah_vanexa01/vanexa-agent` versions in the
+  published 1.1.51 through 1.3.45 set. Its current OpenSSF record remains under
+  `osv/malicious`; no withdrawal was found during this review.
+
+The dispute issue remains open. The withdrawn status of one advisory does not
+withdraw the other or prove that every historical release was safe.
+
+Sources: [dispute issue 1470](https://github.com/ossf/malicious-packages/issues/1470),
+[withdrawn MAL-2026-13397 record](https://github.com/ossf/malicious-packages/blob/main/osv/withdrawn/npm/%40vanexalabs-ai/vanexa-agent/MAL-2026-13397.json),
+[active MAL-2026-13364 record](https://github.com/ossf/malicious-packages/blob/main/osv/malicious/npm/%40ikbal_fadilah_vanexa01/vanexa-agent/MAL-2026-13364.json),
+and [withdrawal pull request 1473](https://github.com/ossf/malicious-packages/pull/1473).
+
+## Historical package evidence
+
+The npm tarballs were fetched with lifecycle scripts disabled and inspected
+locally. Their SHA-256 hashes provide a reproducible identity for this review:
+
+| Package | Version | Tarball SHA-256 | Material finding |
+| --- | ---: | --- | --- |
+| `vanexa-agent` | 1.1.48 | `57b933623759f88719d8ed8dce5e841f76ff6b576f8a30f227bb28bdabcdbd3e` | Included install scripts and a `postinstall` hook that compiled a readable bundle to V8 bytecode. This package is not named by the two records above, but it did execute code during installation. |
+| `@ikbal_fadilah_vanexa01/vanexa-agent` | 1.3.45 | `69501eb9af623472b8e551cfeef98dd2ceacce32a5e8a14b01b2fb8631d8516d` | Included readable bundled source and bytecode, plus `werift`, `ws`, and host-execution dependencies. It had no npm install lifecycle hook in this tarball. |
+| `@vanexalabs-ai/vanexa-agent` | 1.3.62 | `aaf0b65621a9b4d3579cbf31bbb07610efe67e3e2c65a1e414ef49ee6cd46d86` | Shipped bytecode without readable runtime source. Its Socket policy ignored broad malware, obfuscation, shell, filesystem, network, native-code, and install-script categories. |
+| `@vanexalabs-ai/vanexa-agent` | 1.9.19 | `6491307e8d8ae253a3f97514f079fa00b4b8607606cfd9dd53fe0f7cc55adc38` | Still shipped a bytecode-only runtime with `bytenode` and `ws`; the inspected manifest had no npm install lifecycle hook. This version is outside MAL-2026-13397's affected set. |
+
+The reports describe a phone-paired daemon that accepted commands over remote
+signaling or data channels and dispatched them to host execution. The preserved
+legacy source contains that architecture, relay endpoints, daemon lifecycle,
+pairing, WebRTC code, bytecode build logic, and deliberate string-obfuscation
+steps. Those facts explain why the old package shape attracted remote-access
+and concealment concerns even where the intended use was consensual.
+
+## Current Causyne package
+
+The active source takes a different architecture and distribution path:
+
+- It is a foreground local CLI. Pairing, phone control, relays, WebRTC/P2P,
+  background daemon lifecycle, and remote headless command intake are absent.
+- `bytenode`, `werift`, and `ws` are not production dependencies. The package
+  ships readable source and has no install, postinstall, prepare, or automatic
+  update hook.
+- Automatic Cortex dependency installation is disabled. Optional capability
+  packages use a fixed version allowlist, require an approval-class capability
+  grant, install into local Causyne state, and use `npm install --ignore-scripts`.
+- Arbitrary binary/model download actions were removed from the dependency
+  manager. Missing engine checks no longer create a placeholder and report a
+  false successful installation.
+- Python package setup passes arguments without a shell and accepts exact PyPI
+  pins only. URLs, VCS references, paths, options, and unpinned requirements are
+  rejected.
+- The Palmier adapter cannot install third-party applications, and the Astryx
+  adapter no longer auto-installs a package through `npx --yes`.
+- `web_fetch` downloads and curated game-asset downloads require the highest
+  approval class. Curated assets are size-limited, constrained to catalog URLs,
+  protected from output path traversal, and are not automatically extracted.
+- The package allowlist excludes the legacy archive, Android source, private
+  operating documents, credentials, installers, bytecode, and generated
+  tarballs.
+
+At review time, `npm audit --omit=dev` reported zero known vulnerabilities in
+the active locked production graph. npm's audit metadata counted 106 production
+dependencies, and no dependency lifecycle scripts were recorded in the
+lockfile.
+
+## Remaining risk
+
+Causyne Agent is designed to operate on files, processes, applications, model
+providers, and user-configured MCP servers. These capabilities can cause harm
+when a request is wrong, approval is careless, a dependency is compromised, or
+policy enforcement is bypassed. The application policy is not an operating
+system security boundary.
+
+The licensor confirmed on 2026-10-19 that the project-authored source, skills,
+tests, and assets are original work or otherwise lawful to distribute. A
+separate independent security review has not been completed. Optional
+capability graphs must be audited when installed because they are outside the
+main lockfile and can change after this review.

package/docs/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,49 @@
+# Third-party software review
+
+Review date: 2026-10-19.
+
+Causyne Agent's npm package declares third-party packages as dependencies; it
+does not bundle their source into the project tarball. Each dependency remains
+under its own license. The locked graph reviewed on this date contained these
+license identifiers:
+
+| License expression | Lockfile package entries |
+| --- | ---: |
+| MIT | 87 |
+| Apache-2.0 | 22 |
+| BSD-2-Clause | 8 |
+| ISC | 5 |
+| BSD-3-Clause | 1 |
+| BlueOak-1.0.0 | 1 |
+| 0BSD | 1 |
+| MIT OR CC0-1.0 | 1 |
+
+The lockfile contained 126 dependency entries in total. npm's audit metadata
+reported 106 production dependencies; platform-specific optional entries and
+development dependencies account for the differing views of the graph.
+
+The direct runtime dependencies are `@babel/parser`, `acorn-walk`, `commander`,
+`duck-duck-scrape`, `googlethis`, and `inquirer`. Direct
+development dependencies are `@types/node`, `acorn`, and `typescript`. Exact
+versions and integrity hashes are recorded in `package-lock.json`.
+
+No dependency in the reviewed main lockfile was marked with an install script.
+Optional capability dependencies are installed only after approval into a
+separate local environment and are not covered by the main lockfile review.
+
+Repository scanning found no third-party copyright header or license marker in
+the project-authored source and skill files. That negative scan alone cannot
+establish authorship or permission. On 2026-10-19, the licensor confirmed that
+the project-authored source, native skills, tests, and assets are original work
+or can lawfully be distributed under the stated terms.
+
+BUSL-1.1 applies only to Causyne-owned material. It does not replace or narrow
+the licenses of third-party dependencies.
+
+The terms section of `LICENSE` was normalized and compared with the SPDX
+BUSL-1.1 canonical text during this review; it matched. The project-specific
+parameter block selects the named licensor, Causyne Agent 1.10.1 as the licensed
+work, 2030-08-09 as the change date, and Apache-2.0 as the change
+license. The Additional Use Grant permits production use except a paid
+competing commercial offering as defined in that block. These business terms
+should receive legal review before publication if enforcement is material.

package/native-skills/ai-engineering/context-window-management/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: context-window-management
+description: Handle long conversations or large inputs with a language model. Use when context is exhausted, when cost is high, or when a model forgets earlier instructions.
+---
+
+# Context Window Management
+
+## The two costs
+
+Tokens cost money, and attention is finite. A model given a hundred thousand tokens attends unevenly across them — material in the middle is reliably weakest. Filling the window is not the same as using it.
+
+## Workflow
+
+1. Measure where the tokens go.
+   - System prompt, tool definitions, retrieved context, conversation history, current input. One of these is usually dominant and unexamined — tool definitions in particular grow silently.
+   - **Done when:** the token budget is broken down by section.
+
+2. Order for attention and for caching at once.
+   - Stable content first (system, tools, reference material), volatile last (recent turns, current question). This maximises the cacheable prefix AND puts the question at the end, where recall is strongest.
+   - **Done when:** the prefix is byte-identical across calls and the question is last.
+
+3. Compact history rather than truncating it.
+   - Dropping the oldest messages loses the original intent, which is usually the most important thing in the conversation. Keep the first message, summarise the middle, keep recent turns verbatim.
+   - **Done when:** the original task survives any amount of compaction.
+
+4. Spill large tool outputs instead of inlining them.
+   - Store the full output, put a summary and a reference in the context, and let the model request more. A single large file read should not consume a third of the window.
+   - **Done when:** no single tool result dominates the context.
+
+5. Retrieve rather than include.
+   - Do not put a whole document in the prompt when a retrieval step can select the relevant part. This is cheaper and usually more accurate, because it removes distractors.
+   - **Done when:** included material is selected rather than wholesale.
+
+6. Handle the limit before you hit it.
+   - Detect approaching the ceiling and compact proactively. An overflow error mid-task loses the work.
+   - **Done when:** the system compacts before overflow rather than failing.
+
+## Verification
+
+- The token budget is reported by section.
+- Cache hit rate is measured on repeated calls.
+- A long conversation retains the original instruction after compaction.
+- Approaching the limit triggers compaction, not an error.

package/native-skills/ai-engineering/llm-evaluation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: llm-evaluation
+description: Measure whether a model, prompt, or pipeline change is an improvement. Use before shipping any prompt or model change, and when quality is being debated from anecdotes.
+---
+
+# LLM Evaluation
+
+## Why anecdotes fail here
+
+Model output is non-deterministic and its failures are uneven. A change that fixes the three cases you tried can break twenty you did not. Without a fixed set, every prompt change is a guess and quality drifts in both directions unnoticed.
+
+## Workflow
+
+1. Build the set from real failures.
+   - Start with cases the system got wrong in production. Fifty realistic cases beat five hundred synthetic ones. Include the ambiguous, the adversarial, and the out-of-scope.
+   - **Done when:** the set contains every failure mode you have actually observed.
+
+2. Choose the grader to match the task.
+   - Exact match or a schema check for structured output — cheap and exact, use it wherever it applies.
+   - A programmatic check for verifiable properties: does the code run, is the citation real, is the total correct.
+   - A model grader for open-ended quality, with a rubric and a calibration set showing it agrees with human judgement.
+   - Human review for the final call on anything user-facing.
+   - **Done when:** every case has a grader and model graders are calibrated against human labels.
+
+3. Fix the seed and pin the model version.
+   - A provider silently updating a model version invalidates every comparison. Pin explicitly and record it with the results.
+   - **Done when:** results record the exact model version and parameters.
+
+4. Compare against a baseline, always.
+   - A score means nothing alone. Run the current version and the change on the same set, and report both.
+   - **Done when:** every result is a paired comparison.
+
+5. Look at regressions, not just the average.
+   - A change that lifts the mean while breaking five previously-passing cases is usually not worth shipping. Report what got worse.
+   - **Done when:** the per-case diff is reviewed, not just the aggregate.
+
+6. Run it in CI.
+   - A manual evaluation is run when someone remembers. Gate on the regression count.
+   - **Done when:** a prompt change with regressions fails the build.
+
+## Verification
+
+- The set covers every known failure mode.
+- Results are paired against a baseline on a pinned model version.
+- Per-case regressions are reported.
+- CI runs the evaluation on prompt changes.

package/native-skills/ai-engineering/model-cost-and-latency/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: model-cost-and-latency
+description: Reduce the cost or latency of a language-model feature. Use when spend is higher than expected, when responses are slow, or when choosing a model.
+---
+
+# Model Cost and Latency
+
+## Where the money goes
+
+Input tokens, usually. A long system prompt sent on every request dominates spend far more often than output length does. Measure before optimising anything.
+
+## Workflow
+
+1. Instrument per-call cost and latency.
+   - Input tokens, output tokens, cached tokens, model, and latency, tagged by feature. Without this you are optimising by anecdote.
+   - **Done when:** cost per feature is visible on a dashboard.
+
+2. Maximise prompt caching.
+   - Put stable content first and keep the prefix byte-identical. A cached prefix is dramatically cheaper and faster, and this is usually the single largest available win — before any model change.
+   - **Done when:** the cache hit rate is measured and the prefix is stable.
+
+3. Route by difficulty.
+   - Most requests do not need the largest model. Use a small fast model by default and escalate on a measurable signal — low confidence, a failed validation, or a complexity classifier.
+   - **Done when:** the routing rule is stated and its accuracy is measured on the evaluation set.
+
+4. Stream to fix perceived latency.
+   - Time to first token is what users feel. Streaming makes a slow response feel responsive without making it faster.
+   - **Done when:** the user sees output within a few hundred milliseconds.
+
+5. Cut the input before cutting the model.
+   - Trim the system prompt, remove unused tool definitions, retrieve less and rank better. Halving the input often costs no quality at all, where a smaller model might.
+   - **Done when:** every section of the prompt has been justified against its token cost.
+
+6. Cache complete responses where the input repeats.
+   - Identical or near-identical requests do not need a second call. Semantic caching catches paraphrases, with a similarity threshold tuned to avoid wrong hits.
+   - **Done when:** repeated questions are served without a model call.
+
+7. Verify quality did not regress.
+   - Every cost reduction must be checked against the evaluation set. A cheaper wrong answer is not cheaper.
+   - **Done when:** the evaluation score is unchanged or the trade-off is stated explicitly.
+
+## Verification
+
+- Cost per request is reported before and after.
+- Cache hit rate is measured.
+- Evaluation scores are unchanged, or the regression is quantified and accepted.

package/native-skills/ai-engineering/prompt-construction/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: prompt-construction
+description: Write or repair a prompt for a language model. Use when model output is inconsistent, when a prompt has grown by accretion, or when building any LLM-backed feature.
+---
+
+# Prompt Construction
+
+## The shape that works
+
+Role and task, then constraints, then the input, then the required output shape. Put the instruction BEFORE long context: attention to instructions degrades when they are buried after thousands of tokens of material.
+
+## Workflow
+
+1. State the task in one sentence, then the constraints as a list.
+   - Prose paragraphs of mixed instruction and context are where prompts go to become unmaintainable. A list is auditable.
+   - **Done when:** the task is one sentence and every constraint is a separate line.
+
+2. Say what NOT to do, explicitly.
+   - The highest-leverage lines in most prompts. "Do not invent a citation." "Do not answer if the context does not contain the answer." Negative constraints are what stop the confident wrong answer.
+   - **Done when:** the failure modes you have actually observed each have a prohibition.
+
+3. Specify the output format precisely, and validate it.
+   - Ask for a named schema and parse the result. Where the provider supports structured output or tool calling, use it — that is a hard guarantee rather than a request.
+   - **Done when:** the response is parsed into a validated type, and a parse failure is handled.
+
+4. Show, do not only tell.
+   - Two or three examples covering the boundary cases outperform paragraphs of description. Include a hard case and an ambiguous one; examples that are all easy teach nothing.
+   - **Done when:** examples cover the cases the description leaves ambiguous.
+
+5. Order for caching.
+   - Put stable content first — system instructions, tool definitions, long reference material — and volatile content last. Providers cache a matching prefix, so this ordering is the single largest cost reduction available on a repeated prompt.
+   - **Done when:** the prefix is identical across calls.
+
+6. Change one thing at a time and measure.
+   - A prompt edited by feel, several changes at once, cannot be attributed. Keep a small evaluation set.
+   - **Done when:** each change has a before and after score on the evaluation set.
+
+## Verification
+
+- The output parses into the declared schema every time across the evaluation set.
+- Each observed failure mode has a constraint addressing it.
+- The stable prefix is identical between calls.

package/native-skills/ai-engineering/retrieval-augmented-generation/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: retrieval-augmented-generation
+description: Build or fix a retrieval system that feeds a language model. Use when answers cite the wrong source, when retrieval returns irrelevant chunks, or when building search over documents.
+---
+
+# Retrieval-Augmented Generation
+
+## Where these systems actually fail
+
+Almost never in the generation step. They fail in retrieval — the right passage was not in the top results, so the model answered from its own parameters and sounded equally confident. Debug retrieval first, always.
+
+## Workflow
+
+1. Evaluate retrieval on its own.
+   - Build a set of questions with known correct sources. Measure recall at k. If the right chunk is not retrieved, no prompt change can fix the answer.
+   - **Done when:** recall at k is measured and reported separately from answer quality.
+
+2. Chunk on structure, not on length.
+   - Split at headings, paragraphs and other semantic boundaries. A fixed character split cuts sentences in half and produces chunks that mean nothing alone. Include the document title and heading path in each chunk so it is self-describing.
+   - **Done when:** a randomly sampled chunk is comprehensible in isolation.
+
+3. Combine keyword and vector search.
+   - Vector search misses exact identifiers, error codes and rare proper nouns; keyword search misses paraphrase. Hybrid retrieval with reciprocal rank fusion beats either alone on almost every corpus.
+   - **Done when:** both retrievers run and their results are fused.
+
+4. Rerank the candidates.
+   - Retrieve broadly, then rerank with a cross-encoder and keep a few. This consistently produces the largest quality gain per unit of effort in the whole pipeline.
+   - **Done when:** a reranking stage exists and its effect on recall is measured.
+
+5. Make grounding enforceable.
+   - Instruct the model to answer only from the context and to say so when the context is insufficient. Require a citation per claim, and verify the citation points at retrieved text.
+   - **Done when:** a question with no supporting context produces a refusal, not an invention.
+
+6. Handle the update path.
+   - Documents change. Re-embedding everything on each change does not scale; track content hashes and re-embed only what changed.
+   - **Done when:** updating one document does not require a full reindex.
+
+## Verification
+
+- Retrieval recall is measured against a labelled set.
+- An out-of-corpus question is refused rather than answered.
+- Every claim in an answer maps to a retrieved passage.