@vortex-os/base 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vortex-os/base",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Base entry point for VortEX — a Multi-Agent Personal AI Work OS framework",
   "license": "MIT",
   "author": "vortex-os-project",

package/templates/commands/curate.md

@@ -0,0 +1,48 @@
+---
+description: Propose capturing the current work into a knowledge-base document (you decide, never auto-written)
+allowed-tools: Bash(npx vortex:*)
+---
+Offer to capture the user's accumulated work on the CURRENT topic into a
+document — only when it is genuinely worth keeping, and only with the user's
+explicit yes.
+
+INVARIANTS (never break these):
+- NEVER auto-write. Always ask the user before writing anything.
+- ASK before accept — a write happens only after the user says yes.
+- DOCUMENTS only. No hub files, no `_*` / system directories
+  (worklog, decision-log, runbooks, hubs, _memory, _templates, _proactive-curator).
+- No whole-file replace. Only `create-file` (new file) or `append-section`
+  (add a section to an EXISTING file). Never overwrite an existing file.
+- ALWAYS go through the CLI validate/write path below — never write files yourself.
+
+THROTTLE: propose at a TOPIC BOUNDARY when substantial work on ONE topic has
+accumulated — not every turn. If the user waved off curation earlier this
+session, drop it and stay silent.
+
+Steps:
+1. Decide continuation vs new. From the instance root run:
+   `npx vortex curate-candidates`
+   Parse `candidates[]` (each has `relpath`, `topic`, `tags`). If the current
+   work matches an existing document's topic/tags → propose APPENDING to it
+   (`append-section`). Otherwise → propose a NEW file (`create-file`).
+2. Build the proposal payload (JSON):
+   - create-file:    `{ "action":"create-file", "topic":"<1-3 words>",
+                        "targetRelPath":"<data-relative FOLDER>",
+                        "filename":"<slug>.md", "body":"<full document>" }`
+   - append-section: `{ "action":"append-section", "topic":"<1-3 words>",
+                        "targetRelPath":"<data-relative EXISTING file>",
+                        "sectionHeader":"<heading>", "body":"<section text>" }`
+3. (Optional) Dry-check it — writes nothing:
+   `npx vortex curate-preview --payload '<json>'`
+   If `previouslyDeclined` is true → the user already declined this exact
+   proposal; do NOT re-propose it. Stay silent.
+4. Ask the user ONCE, plainly:
+   "Want me to capture this? **new doc** at `<path>`, or **append** to
+   `<existing>`?" — one question, their call.
+5. On YES:  `npx vortex curate-accept  --payload '<json>'`  (writes via the
+   safe path; refuses to overwrite). Then tell them where it landed.
+   On NO:   `npx vortex curate-decline --payload '<json>'`  (suppresses this
+   proposal for 30 days). Then move on.
+
+Keep it light. This is an offer, not a report — one short proposal, never a wall
+of text, never a second ask if they declined.

package/templates/routers/AGENT.md

@@ -7,7 +7,7 @@ status: active
 
 > A vortex absorbing context, an executable runtime running it through agents.
 
-This is the unified entry point for every agent working in this instance (Claude Code, Codex CLI, Gemini CLI, Cursor). The per-agent files (`CLAUDE.md`, `CODEX.md`, `GEMINI.md`, `.cursorrules`) all route here — this file is the single source of truth.
+This is the unified entry point for every agent working in this instance (Claude Code, Codex CLI, Gemini CLI, Cursor). The per-agent files (`CLAUDE.md`, `AGENTS.md`, `CODEX.md`, `GEMINI.md`, `.cursorrules`) all route here — this file is the single source of truth.
 
 This instance was created from the `@vortex-os/base` framework. The framework code lives in `node_modules/@vortex-os/`; you do not edit it. You work in `data/` — your own content — and use the `vortex` CLI and the `/`-commands it installs.
 
@@ -44,6 +44,8 @@ The line is technical: **append-only operational logs are safe to auto-write; st
 
 **Ask one decision at a time.** When you need the user to decide, ask a single question and wait — do not stack several at once. Only batch when the choices are genuinely independent.
 
+**Match reasoning effort to the task.** Don't over-reason trivial asks — a status check, a one-line edit, a lookup; don't under-reason heavy ones — architecture design, multi-file refactors, large debugging or migration, broad reviews. If the host exposes a tunable reasoning/thinking level and the task ahead clearly needs a different one than the session is set for, recommend the change — but rarely: only at a real boundary (a sizable task's start, a major topic shift, a substantial new directive), one or two times across a long session, never per question.
+
 ## The `data/` layout
 
 Your content lives under `data/`. Each category answers a different question:
@@ -84,7 +86,7 @@ You can also run any of these directly: `npx vortex <command> [args]`.
 | Agent | Entry | Shared config | Dedicated config |
 |---|---|---|---|
 | Claude Code | `CLAUDE.md` → `AGENT.md` | `.agent/` | `.claude/` |
-| Codex CLI | `CODEX.md` → `AGENT.md` | `.agent/` | `.codex/` |
+| Codex CLI | `AGENTS.md` → `AGENT.md` (Codex auto-loads `AGENTS.md`; `CODEX.md` is legacy/manual) | `.agent/` | `.codex/` |
 | Gemini CLI | `GEMINI.md` → `AGENT.md` | `.agent/` | `.gemini/` |
 | Cursor | `.cursorrules` → `AGENT.md` | `.agent/` | `.cursor/` |
 

package/templates/routers/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+This is the file Codex CLI (and other `AGENTS.md`-aware agents) auto-loads when
+working in this VortEX instance.
+
+## Route to unified entry
+
+Read [`AGENT.md`](./AGENT.md) first — it is the single source of truth for how
+this instance behaves. This `AGENTS.md` is only the auto-load entry point; the
+full, host-agnostic behavior contract lives in `AGENT.md`.
+
+## Working in a VortEX instance (summary)
+
+VortEX rituals are agent-mediated: run the thin `vortex` CLI and present its JSON
+result to the user in plain language — e.g. `npx vortex status`,
+`npx vortex agenda`, `npx vortex recall "<query>"`, `npx vortex log "<update>"`.
+Never hand-write into the reserved system directories under `data/`
+(`worklog`, `decision-log`, `runbooks`, `hubs`, any `_*`) — go through the CLI.

package/templates/routers/CLAUDE.md

@@ -14,3 +14,7 @@ This `CLAUDE.md` holds only Claude Code-specific supplements. For everything els
 - Shared dir: `.agent/`
 
 `.claude/settings.json` and `.claude/commands/` are populated by `vortex init` — it wires the SessionStart / SessionEnd hooks (`npx --no-install -p @vortex-os/base vortex session-start` / `… session-end`) and installs the agent-mediated slash-commands.
+
+## Reasoning effort
+
+Claude Code exposes a reasoning/effort level you cannot read as a value. When `AGENT.md` → "Working style" calls for an effort change, recommend a *target* ("this looks like high-effort work — raise it if you're below that") rather than asserting the current setting. The user changes it on their side; it takes effect from the next turn, not the current one.

package/templates/routers/CODEX.md

@@ -1,6 +1,8 @@
 # CODEX.md
 
-This is the first file Codex CLI reads when working in this VortEX instance.
+NOTE: Codex CLI auto-loads `AGENTS.md`, not this file. The auto-load entry for
+Codex is `AGENTS.md` (which routes to `AGENT.md`). This `CODEX.md` is a manual /
+legacy supplement — read it only when explicitly pointed here.
 
 ## Route to unified entry