@vortex-os/base 0.7.1 → 0.8.0

package/package.json

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

package/templates/commands/handoff.md

@@ -0,0 +1,24 @@
+---
+description: Leave a clean hand-off in today's worklog so the next session resumes where this one stops — a `## 다음 작업` / `## Next` section with concrete next steps, current state, and pointers.
+allowed-tools: Bash(npx vortex:*), Bash(git add:*), Bash(git commit:*), Read, Edit, Write, Glob
+---
+Capture a hand-off into today's worklog so the NEXT session — a fresh, empty context window — can resume exactly where this one stops, instead of re-deriving everything. Use this at wind-down, or whenever the user says "hand off / wrap up so I can resume / 이어가게 정리 / 인수인계". (This is also a default behavior on those phrases — the command just makes it explicit.)
+
+INVARIANTS (never break):
+- **Append-only.** Add — or update — a hand-off SECTION; never rewrite or reorder the rest of the worklog. Today's `## 다음 작업` section is the one living block you may keep editing.
+- **Real, not padding.** Write what genuinely remains and how to resume. If nothing is pending, say so plainly rather than inventing tasks.
+- **Commit is offered; push stays explicit.** Offer to commit the hand-off for durability; push only if the user asks.
+
+## 1. Find or create today's worklog
+- One worklog per topic/session is fine and encouraged — a distinct piece of work can take its own `data/worklog/<YYYY>/<MM>/<YYYY-MM-DD>-<keyword>.md`.
+- To append to today's existing worklog, `npx vortex log "다음 작업"` scaffolds an empty `## 다음 작업` section. It errors if today has no worklog yet — then create the file first (with worklog frontmatter), or run `npx vortex init` once on a brand-new instance.
+- Position doesn't matter: the start-of-session report finds the section by its heading, in any of the day's worklogs.
+
+## 2. Fill the hand-off section
+In the `## 다음 작업` (or `## Next`) section, write, in this order:
+1. **Next steps — concrete, as unchecked `- [ ]` items, first.** Each one a single action the next session can pick up directly. (Completed steps belong checked off as `- [x]` — the start report skips those, surfacing only what's left.)
+2. **Current state** — what's done vs in progress, and any decision already made.
+3. **Pointers to resume from** — the files, commit hashes, and decision-log entries the next session will need.
+
+## 3. Make it durable
+Briefly confirm what you captured, then offer to commit it (and, only if the user asks, push) so the hand-off survives into the next session — and across machines, if the instance syncs.

package/templates/manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "vortex-template-index/1",
-  "baseVersion": "0.7.1",
+  "baseVersion": "0.8.0",
   "files": [
     {
       "templateId": "commands/agenda.md",
@@ -12,6 +12,11 @@
       "path": "commands/curate.md",
       "sha256": "6cbb7611841fa9f5109f81afadfa5fe85ae3d21049e9905c9e30a38c0483a536"
     },
+    {
+      "templateId": "commands/handoff.md",
+      "path": "commands/handoff.md",
+      "sha256": "0b37e280b53713eda5e6ca6f60535b5b549e5e823f8d0f549bd952f289c18b44"
+    },
     {
       "templateId": "commands/recall.md",
       "path": "commands/recall.md",
@@ -40,12 +45,12 @@
     {
       "templateId": "routers/AI-RULES.md",
       "path": "routers/AI-RULES.md",
-      "sha256": "a5fff6fc53ddc312fb744e2c53fb69e2f82e453716f8f3114716ce2503906302"
+      "sha256": "f82bcdf6b55ca1f4ba59f940ff38947138815e095d8905658fcb0a300fe67d0e"
     },
     {
       "templateId": "routers/CLAUDE.md",
       "path": "routers/CLAUDE.md",
-      "sha256": "36b1b475de280a8e36fe7562574af19a0820c89f4211bef00435ac00c6c95392"
+      "sha256": "c704efa4effc974f0bc0c7c336b0db15e22fc76f582675742c44bd6bfdc79a25"
     },
     {
       "templateId": "routers/GEMINI.md",

package/templates/routers/AI-RULES.md

@@ -31,6 +31,7 @@ Operating principle: **auto-maintain the operational memory; propose changes to
 **Auto (no prompt — append-only operational records; *show, don't ask*):**
 - **Session start.** Run the start ritual: if a sync remote is configured, `git pull` (report conflicts, never auto-resolve); detect the environment if one is configured (and if a label resolves with a matching `.agent/env/<label>.md`, read that file as session-specific operating guidance); backfill any worklog missing from prior sessions; **load your `data/_memory/` always-on rules and scan its `_INDEX.md`** (see "The `data/` layout" → memory loading); report status. If the `SessionStart` hook is configured, the **data-side** ritual already ran and its report was **injected into your context — the user has NOT seen it. Start your first reply by relaying the key points: recent work, what's in progress, the time, any update notices, and any warnings.** If no hook ran, perform the ritual yourself first, then report the same status. (Automatic means the records updated on their own — informing the user is still your job.)
 - **Worklog.** As a work unit completes — and at session wind-down ("that's it for today", "wrap up") — ensure today's worklog exists and append the work. The agent is the primary path; the `SessionEnd` hook is the net.
+- **Session hand-off.** At wind-down — or whenever the user asks to hand off / continue later ("hand off", "wrap up so I can resume", "leave it for next time", "인수인계") — make sure today's worklog carries a clearly-headed hand-off section (`## 다음 작업` / `## Next`): the concrete next steps as unchecked `- [ ]` items, plus the current state and the pointers to resume from (files, commit hashes, decisions). The next session's start report surfaces that section automatically — it finds it by heading, in any of the day's worklogs, at any position — so the next session resumes from a clean window instead of re-deriving context. A distinct piece of work can take its own dated worklog (`YYYY-MM-DD-<keyword>.md`); every entry sharing the latest day is surfaced, so nothing is buried.
 - **Decisions.** When the user makes a *substantive* decision ("let's go with X"), record it in the Decision Log. Real decisions, not casual asides.
 - **Ambient recall** (read-only). When the user references earlier work, run `/recall <the reference>` and weave a confident hit into one sentence. One nudge, not a list; drop it if waved off. Conversations are vectorized automatically at session start. With the `@vortex-os/memory-extended` add-on installed, the first session also sets recall up on its own — downloading the local search model (~470 MB, once) in the **background** — so recall and these ambient lookups just work with no prompt and no manual step (the session-start report notes the one-time download while it runs; relay that). To keep that download manual instead (metered line, CI), set `autoRecord.vectorizeAutoDownload: false` (or env `VORTEX_VECTORIZE_AUTO_DOWNLOAD=0`) and set it up once with `/recall` or `vortex vectorize`.
 
@@ -91,7 +92,7 @@ Your content lives under `data/`. Each category answers a different question:
 
 | Category | Question it answers |
 |---|---|
-| `worklog/` | "What happened today?" — chronological, one entry per day (`YYYY/MM/YYYY-MM-DD-keyword.md`). |
+| `worklog/` | "What happened today?" — chronological; one **or more** entries per day, one per topic/session is fine and encouraged (`YYYY/MM/YYYY-MM-DD-keyword.md`). |
 | `decision-log/` | "Why did we choose X over Y?" — per-decision record with context + alternatives. |
 | `_memory/` | "What rule or fact must survive every session?" — curated; loads in two tiers (below). |
 | `runbooks/` | "What is the procedure when X breaks?" — repeatable steps with `last_tested` aging. |
@@ -117,6 +118,7 @@ These slash-commands are installed into `.claude/commands/` by `vortex init` (th
 | `/vortex global-setup` | Use VortEX from **any** folder — merges an instance pointer + session hooks into your global `~/.claude` (merge-safe, idempotent; `--decline` to dismiss the offer). |
 | `/session-start` | Start-of-session report — recent work, current counts, the time. |
 | `/log <section>` | Append a section to today's worklog (creates it if needed). |
+| `/handoff` | Leave a clean hand-off in today's worklog (`## 다음 작업` — next steps + current state + pointers) so the next session resumes where you stopped. Also fires on "hand off / wrap up / 인수인계". |
 | `/decision <slug> <title>` | Create a new Decision Log entry from the template. |
 | `/recall <query>` | Keyword + semantic (hybrid) search over your memories and past sessions; the agent picks the mode. *(Only when the optional `@vortex-os/memory-extended` add-on is installed.)* |
 | `/agenda` | "What should I focus on?" — synthesizes open tasks, decisions, recent activity. |

package/templates/routers/CLAUDE.md

@@ -1,39 +1,39 @@
-# CLAUDE.md
-
-This is the first file Claude Code reads when working in this VortEX instance.
-
-## Shared rules (required — auto-loaded)
-
-The rules shared by every agent in this instance live in `AI-RULES.md`, imported here so Claude Code loads it automatically at launch:
-
-@AI-RULES.md
-
-This `CLAUDE.md` holds only Claude Code-specific supplements; everything shared is in `AI-RULES.md` (above).
-
-## Claude Code-specific config
-
-- Dedicated dir: `.claude/`
-- 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 `AI-RULES.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.
-
-## Delegating to sub-agents (context economy)
-
-This is the Claude Code mechanism behind `AI-RULES.md` → "Working style" → *delegate heavy, self-contained work*. The point is to spend the **sub-agent's** context on the heavy part and return only the conclusion, so the main thread stays lean across a long day.
-
-- **Task / Agent tool — the usual first reach for self-contained work.** Spawn a sub-agent for one scoped, fully-specifiable job; it runs in its own context and only its final answer comes back. Use the **Explore** agent for "search across the repo and tell me the conclusion" (it reads excerpts, not whole files), and a **general-purpose** agent for a multi-step job you can spell out up front. Give it a precise spec + what "done" looks like and have it return its evidence; **verify what it returns** before building on it. (Not for fuzzy, judgment-heavy, or tightly-coupled work — see `AI-RULES.md` → "Working style".)
-- **Several at once.** When jobs are independent, launch them in one message so they run in parallel (e.g. explore three subsystems at once), then synthesize on the main thread.
-- **Custom agents (`.claude/agents/*.md`).** For a delegation you repeat, define a named specialist once and reuse it. Not installed by default — add when a pattern recurs.
-- **Workflows (multi-agent orchestration).** For breadth one context can't hold — a broad review, an audit, a migration across many files. Token-heavy and fan-out-y, so **only when the user explicitly asks** for that scale; otherwise prefer a few Task agents.
-
-Do **not** delegate the judgment — the main thread owns the plan, the decisions, and the final synthesis. Delegate the reading, the searching, the bulk generation; keep the deciding.
-
-## Cross-check tool (per `AI-RULES.md` → "Cross-check significant decisions")
-
-For the adversarial cross-check that `AI-RULES.md` calls for: use a **Task sub-agent with a clean context** (give it only the relevant facts + acceptance criteria) for a same-model check; if the **Codex CLI** is installed, `codex exec -C <repo> -s read-only` is a stronger **cross-model** check. Bring back only the verdict — the main thread still decides and closes by verifying against the code/tests. When you shell out to `codex exec`: close stdin (`< /dev/null`) so it doesn't stall waiting for input, set your own timeout (the host's may not stop a runaway), and keep the reviewer read-only (`-s read-only`). On **Windows PowerShell** `< /dev/null` doesn't exist — pipe input instead (`git diff | codex exec …`, or `'' | codex exec …` for a non-diff review) to hand stdin an EOF, and pass the prompt as a **single-quoted here-string** (`@'…'@`, closing `'@` at column 0): a double-quoted prompt makes PowerShell treat the backtick as an escape character, so a prompt containing backticks (e.g. a backticked command name like `update --adopt`) fails to parse with an "invalid Unicode escape" error.
-
-For the **security-review** lens (per `AI-RULES.md` → "Security-review code changes"): Claude Code ships a `/security-review` command that reviews the pending diff on the current branch — use it for the security pass. For a stronger or independent check, the same `codex exec -C <repo> -s read-only` (cross-model) or a clean-context Task sub-agent (give it only the diff + the threat surface) applies, prompted for the security classes rather than general correctness.
+# CLAUDE.md
+
+This is the first file Claude Code reads when working in this VortEX instance.
+
+## Shared rules (required — auto-loaded)
+
+The rules shared by every agent in this instance live in `AI-RULES.md`, imported here so Claude Code loads it automatically at launch:
+
+@AI-RULES.md
+
+This `CLAUDE.md` holds only Claude Code-specific supplements; everything shared is in `AI-RULES.md` (above).
+
+## Claude Code-specific config
+
+- Dedicated dir: `.claude/`
+- Shared dir: `.agent/`
+
+`.claude/settings.json` and `.claude/commands/` are populated by `vortex init` — it wires the SessionStart / SessionEnd hooks (`npx --no-install 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 `AI-RULES.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.
+
+## Delegating to sub-agents (context economy)
+
+This is the Claude Code mechanism behind `AI-RULES.md` → "Working style" → *delegate heavy, self-contained work*. The point is to spend the **sub-agent's** context on the heavy part and return only the conclusion, so the main thread stays lean across a long day.
+
+- **Task / Agent tool — the usual first reach for self-contained work.** Spawn a sub-agent for one scoped, fully-specifiable job; it runs in its own context and only its final answer comes back. Use the **Explore** agent for "search across the repo and tell me the conclusion" (it reads excerpts, not whole files), and a **general-purpose** agent for a multi-step job you can spell out up front. Give it a precise spec + what "done" looks like and have it return its evidence; **verify what it returns** before building on it. (Not for fuzzy, judgment-heavy, or tightly-coupled work — see `AI-RULES.md` → "Working style".)
+- **Several at once.** When jobs are independent, launch them in one message so they run in parallel (e.g. explore three subsystems at once), then synthesize on the main thread.
+- **Custom agents (`.claude/agents/*.md`).** For a delegation you repeat, define a named specialist once and reuse it. Not installed by default — add when a pattern recurs.
+- **Workflows (multi-agent orchestration).** For breadth one context can't hold — a broad review, an audit, a migration across many files. Token-heavy and fan-out-y, so **only when the user explicitly asks** for that scale; otherwise prefer a few Task agents.
+
+Do **not** delegate the judgment — the main thread owns the plan, the decisions, and the final synthesis. Delegate the reading, the searching, the bulk generation; keep the deciding.
+
+## Cross-check tool (per `AI-RULES.md` → "Cross-check significant decisions")
+
+For the adversarial cross-check that `AI-RULES.md` calls for: use a **Task sub-agent with a clean context** (give it only the relevant facts + acceptance criteria) for a same-model check; if the **Codex CLI** is installed, `codex exec -C <repo> -s read-only` is a stronger **cross-model** check. Bring back only the verdict — the main thread still decides and closes by verifying against the code/tests. When you shell out to `codex exec`: close stdin (`< /dev/null`) so it doesn't stall waiting for input, set your own timeout (the host's may not stop a runaway), and keep the reviewer read-only (`-s read-only`). On **Windows PowerShell** `< /dev/null` doesn't exist — pipe input instead (`git diff | codex exec …`, or `'' | codex exec …` for a non-diff review) to hand stdin an EOF, and pass the prompt as a **single-quoted here-string** (`@'…'@`, closing `'@` at column 0): a double-quoted prompt makes PowerShell treat the backtick as an escape character, so a prompt containing backticks (e.g. a backticked command name like `update --adopt`) fails to parse with an "invalid Unicode escape" error.
+
+For the **security-review** lens (per `AI-RULES.md` → "Security-review code changes"): Claude Code ships a `/security-review` command that reviews the pending diff on the current branch — use it for the security pass. For a stronger or independent check, the same `codex exec -C <repo> -s read-only` (cross-model) or a clean-context Task sub-agent (give it only the diff + the threat surface) applies, prompted for the security classes rather than general correctness.