@holt-os/holt 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/action-items/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: action-items
+description: Pull decisions, tasks, and owners out of messy notes or a meeting transcript. Use to turn a raw log into a clean follow-up list.
+---
+
+# action-items
+
+## When to use
+
+The user pastes meeting notes, a call transcript, a chat log, or scattered notes and wants the concrete outcomes extracted so nothing gets lost.
+
+## Instructions
+
+1. Read the whole input and separate the substance from the chit-chat. Ignore greetings, tangents, and thinking-out-loud that led nowhere.
+2. Sort what remains into three groups: DECISIONS (what was settled), TODOS (what someone will do), and OPEN QUESTIONS (what is unresolved).
+3. Write each TODO as "owner: task (due date if stated)". If no owner is named, mark it "unassigned". Preserve names and dates exactly as written.
+4. Write each DECISION as a short statement of what was chosen and, if given, why.
+5. Keep each item to one line. Do not invent owners, dates, or actions that were not in the source.
+6. Output the three lists in that order. Omit a list only if it is genuinely empty.
+
+## Example
+
+DECISIONS
+- Ship the beta to the waitlist on Monday, not the public.
+
+TODOS
+- Sam: send the waitlist export to marketing (by Fri).
+- unassigned: write the launch FAQ.
+
+OPEN QUESTIONS
+- Do we gate signups behind an invite code?

package/skills/brief/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: brief
+description: A short briefing on the state of the current folder, using recalled memory plus the user's input. Use to get oriented fast.
+---
+
+# brief
+
+## When to use
+
+The user wants a quick read on what is going on here: what they were working on, what is decided, and what is next. This skill pairs with Holt's memory recall, which surfaces relevant past notes for the current folder.
+
+## Instructions
+
+1. Assume relevant past notes and facts have been injected as context above. Treat them as your source of truth for prior state; combine them with anything new in the user's input.
+2. Synthesize the state into three threads: what is IN PROGRESS, what is DECIDED, and what is OPEN or NEXT.
+3. Lead with the single most important thing: the item that most needs attention or that unblocks the rest.
+4. Keep it scannable: a short intro line, then tight bullets. This is a briefing, not a report.
+5. If the recalled context is thin or empty, say so plainly and ask the user for the one detail that would make the brief useful, rather than guessing.
+6. Do not restate the raw notes; distill them into current status.
+
+## Example
+
+Most important: the migration is blocked on a schema review that has been open three days.
+
+In progress: rewriting the importer; decided: drop the legacy CSV path; open: who signs off on the schema change.

package/skills/code-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: code-review
+description: Review a file or a diff for correctness bugs, edge cases, and simplifications. Use before merging or when a change feels risky.
+---
+
+# code-review
+
+## When to use
+
+The user shares a file, a function, or a diff and wants a focused review. The goal is catching real problems, not restyling working code.
+
+## Instructions
+
+1. Read for real defects first: logic errors, off-by-one and boundary mistakes, unhandled error paths, null or empty cases, security holes (injection, unescaped input, secrets), and resource leaks (unclosed files, sockets, handles).
+2. Then look for clarity and simplification: duplicated logic, dead code, overly clever constructs, and places a simpler shape would do the same job.
+3. Then note style issues, but only if they hurt readability. Skip pure nits unless the user asks for them.
+4. Report each finding as file:line, then what is wrong, then why it matters, then a concrete fix or the corrected snippet.
+5. Rank findings by severity: bugs and security first, then simplifications, then minor. Put the most important at the top.
+6. Be concise. If a change is clean, say so plainly instead of manufacturing feedback.
+
+## Example
+
+- api.ts:42 (bug): the loop uses <= arr.length, so the last iteration reads arr[arr.length] which is undefined. Change to <.
+- api.ts:88 (simplify): this if/else both return the same object with one field flipped; collapse to one return with a ternary.

package/skills/commit/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: commit
+description: Draft a clear commit message from staged changes or a described change. Use when you want a clean, conventional message.
+---
+
+# commit
+
+## When to use
+
+The user has staged changes (or describes a change in words) and wants a well-formed commit message.
+
+## Instructions
+
+1. Write a concise subject line in the imperative mood ("add", "fix", "remove", not "added" or "fixes"). Keep it under about 72 characters and do not end it with a period.
+2. If the change is trivial, the subject alone is enough. Stop there.
+3. If the change is non-trivial, add a blank line, then a short body that explains what changed and why, not how. The diff already shows how.
+4. If unrelated changes are bundled together, note that they would be cleaner as separate commits, but still give a usable message.
+5. Write a plain message. Do not add tool-attribution footers, "generated by" lines, or co-author trailers unless the user explicitly asks.
+6. If the intent is ambiguous from the changes, ask one clarifying question before guessing.
+
+## Example
+
+Subject: fix off-by-one in pagination cursor
+
+Body:
+The cursor advanced past the last page because the bound used <= instead of <, returning an empty final page. Correct the comparison so the last item is included.

package/skills/decide/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: decide
+description: Weigh a decision and give a clear recommendation. Use when the user is stuck between options and wants a reasoned call.
+---
+
+# decide
+
+## When to use
+
+The user faces a choice (which tool, which approach, whether to do something) and wants help thinking it through and a straight recommendation, not just a list of considerations.
+
+## Instructions
+
+1. Restate the decision and the options on the table in one line each, so you are answering the real question.
+2. List the factors that actually matter for this choice: cost, time, risk, reversibility, effort, fit. Drop factors that do not move the decision.
+3. For each option, give honest pros and cons against those factors. Do not stack the deck; name the real downside of the option you prefer.
+4. Make a clear recommendation. State the main reason it wins and the biggest risk it carries.
+5. If the call genuinely hinges on one unknown, do not guess: name that missing fact and ask for it before committing.
+6. Keep it decisive. The user wants a lean, not a shrug.
+
+## Example
+
+Decision: build the export feature now, or ship without it.
+
+Build it: pro, unblocks the biggest customer; con, adds a week.
+Ship without: pro, launch on time; con, that customer may churn.
+
+Recommendation: build it. Losing the anchor customer outweighs a week's delay. Biggest risk: the week slips to two. Missing fact: has the customer given a hard deadline?

package/skills/explain/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: explain
+description: Explain a concept, error message, or piece of jargon in plain language. Use when the user wants to understand something unfamiliar.
+---
+
+# explain
+
+## When to use
+
+The user asks what something means: a concept, an acronym, an error message, a term of art, or a confusing sentence. They want clarity, not a lecture.
+
+## Instructions
+
+1. Say what it is in one plain sentence, no jargon. If you must use a technical term, define it in the same breath.
+2. Say why it matters or where it shows up, so the user knows why they should care.
+3. Give one concrete analogy or a small worked example that makes it click.
+4. Match the level to the audience. If the user asks for "explain to a beginner" or "to a senior engineer", adjust depth, assumed background, and vocabulary accordingly. When unsure, aim for a smart non-expert.
+5. Keep it short. Stop once the idea lands; offer to go deeper rather than front-loading everything.
+
+## Example
+
+Request: explain what a race condition is, to a beginner.
+
+A race condition is when the result of your program depends on which of two things happens first, and you cannot control the order. It matters because it makes bugs that appear only sometimes. Think of two people editing the same shared doc line at the same time: whoever saves last wins, and the other edit silently vanishes.

package/skills/explain-code/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: explain-code
+description: Walk through what a file or function does and how it fits into the wider system. Use to onboard onto unfamiliar code.
+---
+
+# explain-code
+
+## When to use
+
+The user shares a file or function they did not write (or wrote a while ago) and wants to understand what it does, how it works, and how it connects to the rest of the code.
+
+## Instructions
+
+1. Start with a one-line purpose: what this code is for, in plain terms.
+2. Describe the flow and structure: the main steps or branches, in the order they run. Explain intent, not every line.
+3. Call out key dependencies and side effects: what it imports or calls, what state it reads or mutates, what it writes to disk, network, or the console.
+4. Flag any gotchas: assumptions it makes, inputs it does not handle, and non-obvious behavior a reader would trip on.
+5. Match depth to size. A small helper gets a few sentences; a large module gets a section per responsibility. Do not restate the code line by line.
+6. If something is genuinely unclear or looks buggy, say so rather than inventing a rationale.
+
+## Example
+
+Purpose: parses a config file and returns a typed settings object.
+
+Flow: reads the file, tries JSON.parse, falls back to defaults on any error, then validates required keys.
+
+Gotcha: it swallows parse errors silently, so a malformed config looks identical to a missing one.

package/skills/plan/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: plan
+description: Break a goal into a concrete, ordered set of steps. Use when a task is big enough to need sequencing before starting.
+---
+
+# plan
+
+## When to use
+
+The user states a goal or a task and wants it broken into an actionable, ordered plan they can execute or hand off.
+
+## Instructions
+
+1. Restate the goal in one line so the target is unambiguous.
+2. List the steps in the order they must happen. Each step gets a clear done-condition: how you will know it is finished.
+3. Flag dependencies explicitly (step 4 needs step 2 done first) so the sequence is not just a wish list.
+4. Call out the riskiest or most uncertain step, the one most likely to blow up the timeline, so it can be tackled or de-risked early.
+5. Keep it actionable, not aspirational. Prefer "write the migration script and run it on a copy" over "improve the database".
+6. End with the single immediate next action the user should take right now.
+
+## Example
+
+Goal: move the app from the old auth library to the new one.
+
+1. Inventory every call site of the old library (done: a list exists).
+2. Write an adapter matching the old interface (done: tests pass). RISKIEST: the token refresh path differs.
+3. Swap call sites behind a flag (done: app runs on the flag).
+
+Next action: run the inventory grep in step 1.

package/skills/rewrite/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: rewrite
+description: Tighten and clarify a piece of text without changing its meaning. Use for a neutral clarity pass on text the user provides.
+---
+
+# rewrite
+
+## When to use
+
+The user pastes a paragraph, email, or passage and wants it cleaner and clearer while keeping the same meaning. This is a neutral clarity pass, distinct from a voice-anchored writing task: keep the author's own voice unless a tone is requested.
+
+## Instructions
+
+1. Preserve intent and every fact. Do not add claims, drop caveats, or change the point being made.
+2. Cut filler and hedging: "just", "really", "I think that", "in order to", throat-clearing intros, and redundant phrases.
+3. Prefer plain words over inflated ones ("use" not "utilize", "help" not "facilitate").
+4. Vary sentence length so it reads naturally; break up run-ons, and do not make everything staccato.
+5. Keep the author's voice and register. Only shift tone (more formal, warmer, punchier) if the user asks for it.
+6. Return only the rewritten text, then one short line noting what you changed (for example: "tightened, cut hedging, split two long sentences").
+
+## Example
+
+Before: I just wanted to reach out in order to see if you might possibly have some availability to maybe hop on a quick call sometime.
+
+After: Do you have time for a quick call this week?
+
+Changed: cut hedging and filler, made it a direct ask.

package/skills/summarize/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: summarize
+description: Condense a document, article, transcript, or pasted text into its key points. Use when the input is long and the user wants the gist fast.
+---
+
+# summarize
+
+## When to use
+
+The user pastes or points at a document, article, transcript, email thread, or any long block of text and wants a shorter version that keeps what matters.
+
+## Instructions
+
+1. Read the whole input first and identify its core purpose in one sentence (what it is and why it exists).
+2. Open with a one-line TLDR that captures the single most important takeaway.
+3. Pull the main points: arguments, decisions, numbers, dates, and named people or systems. Keep these verbatim where accuracy matters.
+4. Drop filler: greetings, repetition, hedging, and asides that do not change the meaning.
+5. Scale the output to the input. A few paragraphs get a short bulleted list; a long report gets tight prose grouped by theme. Do not pad.
+6. Do not add facts, opinions, or conclusions that are not in the source.
+
+## Example
+
+TLDR: The team is shipping the payments rewrite next week despite one open risk.
+
+- Decision: launch v2 on the 14th, feature-flagged to 10 percent of users.
+- Open risk: the refund path is untested under load.
+- Owner: Priya to run a load test before Friday.