@newsails/veil-cli 1.0.1

package/examples/skills/code-review.md

@@ -0,0 +1,72 @@
+# Skill: Code Review
+
+This skill provides a systematic checklist and standards for reviewing code.
+
+## Review Order
+
+Always review in this order — from broad to specific:
+
+1. **Architecture** — does the overall structure make sense? Are responsibilities well-separated?
+2. **Correctness** — does the code do what it claims? Are edge cases handled?
+3. **Security** — are there injection risks, exposed secrets, missing auth checks, or unsafe operations?
+4. **Performance** — are there obvious bottlenecks, N+1 queries, blocking calls in async code, or unnecessary re-computation?
+5. **Readability** — are names clear? Is logic obvious? Are comments present where needed?
+6. **Tests** — are tests present? Do they cover the important cases?
+
+## Checklist Per File
+
+When reviewing a single file, check:
+
+- [ ] Functions have a single, clear responsibility
+- [ ] Error cases are handled (not just the happy path)
+- [ ] No hardcoded secrets, credentials, or environment-specific paths
+- [ ] Async operations are awaited; promises are not silently dropped
+- [ ] Input validation is present for untrusted data
+- [ ] No commented-out dead code left in
+- [ ] Variable and function names accurately describe their purpose
+- [ ] No obvious performance issue (large loops, redundant I/O, etc.)
+
+## Severity Levels
+
+Use these labels when reporting issues:
+
+| Level | Meaning |
+|-------|---------|
+| `CRITICAL` | Must fix before shipping — security issue or data loss risk |
+| `HIGH` | Likely bug or serious design flaw |
+| `MEDIUM` | Correctness concern or maintainability issue |
+| `LOW` | Style, naming, or minor improvement suggestion |
+| `NIT` | Tiny stylistic preference — optional |
+
+## Output Format
+
+Structure your code review report as:
+
+```
+## Summary
+Brief overall assessment (2–3 sentences).
+
+## Issues
+
+### CRITICAL
+- [file.js:42] Description of the critical issue and why it matters
+
+### HIGH
+- [file.js:88] Description...
+
+### MEDIUM / LOW / NIT
+- ...
+
+## Positive Observations
+What the code does well — this is not optional.
+
+## Recommendations
+3–5 concrete, prioritised next steps.
+```
+
+## Rules
+
+- Always include "Positive Observations" — finding only problems is incomplete feedback
+- Cite file path and line number for every issue
+- Explain *why* something is a problem, not just *what* is wrong
+- Do not rewrite the code in your review — describe the issue and suggest an approach

package/examples/skills/summarise.md

@@ -0,0 +1,59 @@
+# Skill: Summarisation
+
+This skill defines structure and quality standards for summarisation tasks.
+
+## When to Use Each Format
+
+| Task Type | Format |
+|-----------|--------|
+| Long document → overview | Executive summary + key points |
+| Research findings → report | Structured sections with headers |
+| Meeting notes → actions | Decision log + action items |
+| Code → explanation | What it does, how it works, notable details |
+| Multiple sources → synthesis | Unified narrative, contradictions flagged |
+
+## Executive Summary Format
+
+For any summary that will be read by a decision-maker:
+
+```
+## Summary
+[2–3 sentences covering: what this is about, the main finding or conclusion, and what action (if any) is recommended]
+
+## Key Points
+- Point 1
+- Point 2
+- Point 3
+(3–7 bullet points maximum)
+
+## Details
+[Expanded coverage of each key point for readers who want more]
+```
+
+## Length Guidelines
+
+| Source Length | Target Summary Length |
+|---------------|----------------------|
+| < 500 words | 1–2 sentences |
+| 500–2000 words | 1 paragraph + 3–5 bullets |
+| 2000–10000 words | Executive summary format |
+| > 10000 words | Full structured report |
+
+## Quality Rules
+
+- **Completeness**: The summary must not omit the main conclusion — even if it is uncomfortable or unexpected
+- **Accuracy**: Do not introduce information not present in the source; do not rephrase in a way that changes meaning
+- **Neutrality**: Summarise what the source says, not your opinion of it (unless opinion is explicitly requested)
+- **Specificity**: Avoid vague summaries like "the document discusses various topics" — name the topics
+- **Attribution**: When summarising multiple sources, attribute each key claim: "According to [source]..."
+
+## Synthesis (Multiple Sources)
+
+When combining multiple documents or research outputs:
+
+1. Identify **consensus** — claims supported by multiple sources
+2. Identify **gaps** — topics only one source covers
+3. Identify **contradictions** — claims where sources disagree; flag these explicitly
+4. Write a unified narrative that integrates all three
+
+Never silently drop a source's findings because they are inconvenient — include them.

package/examples/skills/web-research.md

@@ -0,0 +1,42 @@
+# Skill: Web Research
+
+This skill improves the quality and reliability of web research tasks.
+
+## Search Query Construction
+
+- Write specific, targeted queries — avoid vague phrases like "how does X work"
+- Include the domain/technology in the query: `"Node.js SQLite WAL mode performance benchmark"`
+- Add `"site:github.com"`, `"official docs"`, or `"site:developer.mozilla.org"` for authoritative sources
+- Add the current year to queries about recent developments to avoid stale results
+- If a first query returns noise, rephrase using synonyms or the canonical technical term
+
+## Source Quality
+
+| Tier | Examples | Use for |
+|------|----------|---------|
+| Primary | Official docs, GitHub repos, RFCs, research papers | Facts, specifications, APIs |
+| Secondary | MDN, Stack Overflow, major tech publications | Tutorials, best practices |
+| Tertiary | Personal blogs, Medium posts, forum answers | Context only — verify claims independently |
+
+Never cite a source you have not fetched. Search snippets can be misleading.
+
+## Fetching Pages
+
+- Only fetch URLs from primary or secondary sources
+- If `web_fetch` returns an error or a login wall, note it as inaccessible and try an alternative URL
+- Long pages: focus on headings and first paragraphs — read deeper only if the heading is directly relevant
+- PDF links often don't fetch well — note them as "PDF — not fetched" if needed
+
+## Handling Contradictions
+
+If two sources contradict each other:
+1. Note both claims and their sources
+2. Check which source is more authoritative (tier)
+3. Check which is more recent
+4. Report the discrepancy explicitly — do not silently pick one
+
+## Avoiding Hallucination
+
+- Never invent URLs — only cite pages you actually fetched
+- Never paraphrase a source as if it said something it didn't
+- If you cannot find reliable information, state: "I was unable to find a reliable source for this claim"

package/examples/tools/word-count/index.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * word_count — custom tool example.
+ *
+ * Demonstrates the minimal custom tool contract:
+ *   - module.exports.execute(input) → string
+ *   - input params are validated against tool.json input_schema before execute() is called
+ *   - _cwd, _agent, _settings, _taskId are injected by the runtime (not in input_schema)
+ */
+async function execute({ text, includeReadingTime = false }) {
+  const lines = text.split('\n').length;
+  const words = text.trim() === '' ? 0 : text.trim().split(/\s+/).length;
+  const chars = text.length;
+  const charsNoSpaces = text.replace(/\s/g, '').length;
+
+  let result = `Words: ${words}\nCharacters: ${chars} (${charsNoSpaces} without spaces)\nLines: ${lines}`;
+
+  if (includeReadingTime) {
+    const minutes = Math.ceil(words / 200);
+    result += `\nEstimated reading time: ${minutes} min (at 200 wpm)`;
+  }
+
+  return result;
+}
+
+module.exports = { execute };

package/examples/tools/word-count/tool.json

@@ -0,0 +1,18 @@
+{
+  "name": "word_count",
+  "description": "Count words, characters, and lines in a text string. Useful for checking document length before writing to memory or estimating reading time.",
+  "input_schema": {
+    "type": "object",
+    "required": ["text"],
+    "properties": {
+      "text": {
+        "type": "string",
+        "description": "The text to analyse"
+      },
+      "includeReadingTime": {
+        "type": "boolean",
+        "description": "If true, include an estimated reading time (at 200 wpm). Default: false."
+      }
+    }
+  }
+}