@trusted-ai/xbot 0.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@trusted-ai/xbot",
+  "version": "0.1.0",
+  "description": "Rust-native autonomous bot runtime for chat automation, tools, scheduled work, and multi-channel delivery",
+  "license": "MIT",
+  "homepage": "https://github.com/guoqingbao/xbot#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guoqingbao/xbot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/guoqingbao/xbot/issues"
+  },
+  "bin": {
+    "xbot": "bin/xbot.js"
+  },
+  "scripts": {
+    "prepack": "node scripts/prepare-package.js",
+    "postpack": "node scripts/clean-package.js",
+    "postinstall": "node scripts/install.js"
+  },
+  "files": [
+    "bin/xbot.js",
+    "scripts/install.js",
+    "docs/ARCHITECTURE.md",
+    "docs/HYBRID_MODELS.md",
+    "docs/INSTALLATION.md",
+    "docs/OPERATIONS.md",
+    "docs/xbot.png",
+    "docs/USAGE.md",
+    "skills",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "keywords": [
+    "agent",
+    "automation",
+    "chatbot",
+    "llm",
+    "tui"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "arm64",
+    "x64"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const https = require("https");
+const os = require("os");
+const path = require("path");
+const { createHash } = require("crypto");
+const { spawnSync } = require("child_process");
+
+const pkg = require("../package.json");
+
+function targetTriple() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if ((platform !== "linux" && platform !== "darwin") || (arch !== "x64" && arch !== "arm64")) {
+    throw new Error(`Unsupported platform: ${platform}-${arch}. Supported: linux/darwin x64/arm64.`);
+  }
+  return `${platform}-${arch}`;
+}
+
+function download(url, destination, redirects = 0) {
+  if (redirects > 5) {
+    return Promise.reject(new Error(`Too many redirects while downloading ${url}`));
+  }
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, (response) => {
+      if (
+        response.statusCode >= 300 &&
+        response.statusCode < 400 &&
+        response.headers.location
+      ) {
+        response.resume();
+        const next = new URL(response.headers.location, url).toString();
+        download(next, destination, redirects + 1).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Download failed (${response.statusCode}) for ${url}`));
+        return;
+      }
+      const file = fs.createWriteStream(destination);
+      response.pipe(file);
+      file.on("finish", () => file.close(resolve));
+      file.on("error", reject);
+    });
+    request.on("error", reject);
+  });
+}
+
+function sha256(file) {
+  const hash = createHash("sha256");
+  hash.update(fs.readFileSync(file));
+  return hash.digest("hex");
+}
+
+function expectedSha(manifest, artifactName) {
+  for (const line of manifest.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const parts = trimmed.split(/\s+/);
+    const checksum = parts[0];
+    const name = parts[parts.length - 1].replace(/^\*/, "");
+    if (name === artifactName) {
+      return checksum;
+    }
+  }
+  return null;
+}
+
+async function main() {
+  const target = targetTriple();
+  const version = process.env.XBOT_INSTALL_VERSION || pkg.version;
+  const tag = process.env.XBOT_INSTALL_TAG || `v${version}`;
+  const base =
+    process.env.XBOT_INSTALL_BASE_URL ||
+    `https://github.com/guoqingbao/xbot/releases/download/${tag}`;
+  const artifactName = `xbot-${version}-${target}.tar.gz`;
+  const artifactUrl = `${base}/${artifactName}`;
+  const sumsUrl = `${base}/SHA256SUMS`;
+  const root = path.resolve(__dirname, "..");
+  const installDir = path.join(root, "vendor", target);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "xbot-install-"));
+  const archivePath = path.join(tmpDir, artifactName);
+  const sumsPath = path.join(tmpDir, "SHA256SUMS");
+
+  try {
+    await download(sumsUrl, sumsPath);
+    await download(artifactUrl, archivePath);
+    const expected = expectedSha(fs.readFileSync(sumsPath, "utf8"), artifactName);
+    if (!expected) {
+      throw new Error(`No checksum entry found for ${artifactName}`);
+    }
+    const actual = sha256(archivePath);
+    if (actual !== expected) {
+      throw new Error(`Checksum mismatch for ${artifactName}: expected ${expected}, got ${actual}`);
+    }
+
+    fs.rmSync(installDir, { recursive: true, force: true });
+    fs.mkdirSync(installDir, { recursive: true });
+    const tar = spawnSync("tar", ["-xzf", archivePath, "-C", installDir], {
+      stdio: "inherit"
+    });
+    if (tar.error) {
+      throw tar.error;
+    }
+    if (tar.status !== 0) {
+      throw new Error(`tar exited with status ${tar.status}`);
+    }
+    const binary = path.join(installDir, "xbot");
+    fs.chmodSync(binary, 0o755);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err) => {
+  console.error(`xbot install failed: ${err.message}`);
+  process.exit(1);
+});

package/skills/README.md

@@ -0,0 +1,10 @@
+# xbot Built-in Skills
+
+Built-in skills are optional workflow guides that `xbot` can load into the prompt context.
+
+- `workspace-operator`: always-on guidance for safe file, shell, and reporting workflows
+- `memory-hygiene`: always-on guidance for maintaining durable memory and searching history
+- `software-engineer`: coding, verification, and git-oriented engineering workflows
+- `data-analyst`: research, source tracking, and report production workflows
+- `github-cli`: GitHub and CI workflows through the `gh` CLI
+- `scheduled-ops`: cron and long-running automation guidance

package/skills/clawhub/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: clawhub
+description: "Search, install, and update agent skills from ClawHub using the clawhub CLI via npx."
+homepage: https://clawhub.ai
+metadata: {"xbot":{"description":"ClawHub marketplace: npx clawhub search/install/update/list; use --workdir for the xbot workspace.","emoji":"🦞","triggers":["clawhub","skill marketplace","install skill","search skills"],"requires":{"bins":["npx"]}}}
+---
+
+# ClawHub
+
+[ClawHub](https://clawhub.ai) is a public registry of agent skills. Skills are fetched with the **`clawhub`** CLI, typically through **`npx`** so you do not need a global install.
+
+## When to use
+
+Use this skill when the user wants to discover skills, install or update them, or list what is already installed in the workspace.
+
+## Prerequisites
+
+- **Node.js** (includes `npx`). No API key is required for search, install, or list.
+- **`login`** is only needed if the user publishes skills.
+
+## Commands (use `npx clawhub@latest`)
+
+Pin the package so behavior matches current docs:
+
+```bash
+npx clawhub@latest <subcommand> ...
+```
+
+`--yes` (or your package manager’s non-interactive flag) avoids prompts when appropriate:
+
+```bash
+npx --yes clawhub@latest search "web scraping" --limit 5
+```
+
+### Search
+
+Natural-language or keyword search:
+
+```bash
+npx --yes clawhub@latest search "<query>" --limit 5
+```
+
+### Install
+
+Install a skill **into a workspace directory** so xbot can load it (xbot discovers skills under the workspace `skills/` tree—see your xbot config for the exact workspace root).
+
+```bash
+npx --yes clawhub@latest install <slug> --workdir /path/to/xbot/workspace
+```
+
+Replace `<slug>` with the identifier from search results. **Always set `--workdir`** to the xbot workspace root (the directory that contains `.xbot/` and usually `skills/`), not a random cwd—otherwise files land in the wrong place.
+
+### Update
+
+Refresh installed skills from the registry:
+
+```bash
+npx --yes clawhub@latest update --all --workdir /path/to/xbot/workspace
+```
+
+### List installed
+
+```bash
+npx --yes clawhub@latest list --workdir /path/to/xbot/workspace
+```
+
+## xbot-specific notes
+
+- Use the **same `--workdir`** you use for xbot’s configured workspace (often the repo root in development). If unsure, check `agents.defaults.workspace` (or equivalent) in config.
+- After installing or updating skills, a **new agent session** may be needed for newly added `skills/<name>/SKILL.md` files to load.
+- Publishing is optional and requires `npx clawhub@latest login` once.

package/skills/cron/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cron
+description: "Schedule recurring or one-off work with the built-in cron tool (reminders, agent tasks, one-time runs)."
+metadata: {"xbot":{"description":"cron tool: add/list/remove; intervals, cron expressions, one-shot at; timezones.","emoji":"⏰","triggers":["cron","schedule","reminder","timer","periodic"]}}
+---
+
+# Cron tool
+
+The **`cron`** tool schedules jobs stored under `.xbot/cron/` (for example `jobs.json`). Each firing runs an **agent turn** with your message in the same channel/chat context that was active when the job was created. Results are delivered to the user when the run completes successfully.
+
+Actions: `add`, `list`, `remove`.
+
+You cannot create new jobs from inside a job execution (nested scheduling is blocked).
+
+## Modes (how to think about the message)
+
+All jobs use the same mechanism; the difference is how you phrase **`message`** and which schedule you pick:
+
+1. **Reminder** — Short, self-contained text the user should see again (status, nudge, “standup in 5 minutes”). The agent processes it like any other turn; keep it readable as a notification.
+2. **Task** — Instructions that require work each time (check a feed, run a report, summarize metrics). Make the message self-contained so the scheduled run does not depend on missing chat context.
+3. **One-time** — Use the **`at`** parameter once; the job is removed after it runs (or disabled per internal rules). For repeating work, use **`every_seconds`** or **`cron_expr`** instead.
+
+## Parameters (add)
+
+| Parameter | Purpose |
+|-----------|---------|
+| `action` | `"add"` |
+| `message` | Required. Body of the scheduled turn (name is derived from a short prefix). |
+| `every_seconds` | Fixed interval in seconds (minimum 1). |
+| `cron_expr` | Standard five-field cron string (minute hour dom month dow). A six-field form with seconds is accepted; five-field expressions are normalized with a leading `0` for seconds. |
+| `tz` | **Only with `cron_expr`.** IANA name, e.g. `America/Vancouver`. Without `tz`, local server time is used. |
+| `at` | One-shot: ISO datetime. Accepted: RFC3339 (e.g. `2026-04-01T15:30:00-07:00`) or local `YYYY-MM-DDTHH:MM:SS`. |
+
+Exactly one of `every_seconds`, `cron_expr`, or `at` must be supplied for `add`.
+
+## Time expression examples
+
+| Intent | Illustration |
+|--------|----------------|
+| Every 20 minutes | `every_seconds`: `1200` |
+| Every hour | `every_seconds`: `3600` |
+| Daily at 08:00 (server local) | `cron_expr`: `"0 8 * * *"` |
+| Weekdays 17:00 | `cron_expr`: `"0 17 * * 1-5"` |
+| 09:00 weekdays in a specific zone | `cron_expr`: `"0 9 * * 1-5"`, `tz`: `"America/Vancouver"` |
+| Once at a specific instant | `at`: RFC3339 or local ISO string as above |
+
+## List and remove
+
+```text
+cron(action="list")
+cron(action="remove", job_id="<id>")
+```
+
+Use `list` to copy the short `id` for removal.
+
+## Timezone support
+
+- **`tz`** applies **only** to **`cron_expr`** schedules. Invalid or unknown zone names are rejected.
+- **`at`** is parsed as an absolute instant (RFC3339 includes offset) or local naive datetime—know which form you are passing.
+- Interval schedules (`every_seconds`) are wall-clock intervals from the previous scheduling logic, not “9am every day” unless you use `cron_expr` + `tz`.
+
+## See also
+
+- **`scheduled-ops`** — Operational guidance for unattended recurring work.

package/skills/data-analyst/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: data-analyst
+description: "Research, web analysis, evidence gathering, synthesis, and report-writing workflow."
+metadata: {"xbot":{"triggers":["data","analyze","csv","statistics","chart"]}}
+---
+
+# Data Analyst
+
+Use this workflow for recurring research, monitoring, and reporting tasks.
+
+## Workflow
+
+1. Define the question and the output format.
+2. Gather evidence from web search, fetched pages, local files, or command outputs.
+3. Separate raw facts from interpretation.
+4. Save structured notes or reports when the result should be reused.
+5. If the task repeats, schedule it with cron and record the expected deliverable.
+
+## Reporting Standards
+
+- Prefer concise sections: objective, findings, evidence, risks, next actions.
+- Keep source provenance visible when conclusions depend on fetched material.
+- If data is incomplete or unstable, say so explicitly.
+
+## Useful Deliverables
+
+- daily report
+- market snapshot
+- implementation status memo
+- issue triage summary
+- release readiness report

package/skills/delivery-rules/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: delivery-rules
+description: "Workspace template for review, release, and delivery expectations."
+metadata: {"xbot":{"triggers":["deliver","send","message","channel"]}}
+---
+
+# Delivery Rules Template
+
+Use this file to document how work should be delivered in this project.
+
+## Suggested Content
+
+- review expectations
+- test coverage standards
+- release checklist
+- commit or branch conventions
+- deployment safeguards
+
+## Guidance
+
+- Keep this focused on process, not architecture.
+- Update it when the team changes delivery policy.
+- If a rule becomes universal for the workspace, also capture it in `memory/MEMORY.md`.

package/skills/github/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: github
+description: "End-to-end GitHub workflows with gh: PRs, issues, reviews, branches, and releases."
+metadata: {"xbot":{"description":"Broader GitHub practice with gh: workflows, triage, review, branching, releases.","emoji":"🐙","triggers":["github","pull request","issue","release","code review","gh"],"requires":{"bins":["gh"]}}}
+---
+
+# GitHub
+
+This skill complements **`github-cli`** (command cheat sheet) with **workflow** guidance. All examples assume the [GitHub CLI](https://cli.github.com/) (`gh`) is installed and authenticated (`gh auth login`).
+
+Scope:
+
+- **`github-cli`** — Quick reference for common `gh` commands.
+- **This skill** — How to use GitHub effectively: PR lifecycle, issues, review etiquette, branching, and releases.
+
+Always pass **`--repo owner/repo`** when not inside a clone of that repository, or `cd` to the repo first.
+
+## Pull requests
+
+**Open and iterate**
+
+- Branch from the default branch (or the team’s agreed base) with a descriptive name: `feat/…`, `fix/…`, `chore/…`.
+- Keep PRs review-sized; split unrelated changes.
+- Use the PR description to state **intent**, **scope**, and **how to test**; link issues with `Fixes #123` or `Refs #123` when applicable.
+
+**CI and checks**
+
+```bash
+gh pr checks <number> --repo owner/repo
+gh run list --repo owner/repo --limit 10
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+Treat failing checks as blocking unless the team explicitly merges with red CI.
+
+**Review response**
+
+- Push follow-up commits or comment with resolution; resolve review threads when addressed.
+- For stacked work, prefer dependent PRs or a single PR with clear commits—match what the repo already does.
+
+## Issues
+
+**Triage**
+
+- Labels, milestones, and assignees create shared queues; prefer one primary assignee per active item.
+- Reproduce bugs with version, environment, and minimal steps before deep fixes.
+
+**Structured queries**
+
+```bash
+gh issue list --repo owner/repo --label bug --state open
+gh issue view 42 --repo owner/repo
+gh api repos/owner/repo/issues/42 --jq '.title, .body'
+```
+
+Use **`--json`** and **`--jq`** for dashboards and bots.
+
+## Code review patterns
+
+- Start with **intent**: does the change match the problem statement?
+- Check **correctness**, **tests**, **API compatibility**, and **security** (secrets, injection, permissions).
+- Prefer actionable comments (“consider X because Y”); avoid nit-only rounds on style if linters enforce it.
+- Approve when you would be comfortable shipping; request changes when you would not.
+
+## Branch strategies
+
+Match the repository:
+
+- **Trunk-based / short-lived branches** — Small PRs, fast merge, feature flags if needed.
+- **GitFlow-style** — Long-lived `develop` and release branches; only use if the repo already does.
+- **Fork PRs** — Common for OSS; sync default branch before large rebases.
+
+Protect the default branch with required reviews and CI as appropriate.
+
+## Release management
+
+- **Versioning** — Follow SemVer unless the project defines otherwise; tag releases consistently.
+- **Changelog** — Aggregate user-facing changes; link PRs and issues.
+- **Artifacts** — Attach binaries or notes via `gh release create`, CI upload, or project-specific scripts.
+
+```bash
+gh release list --repo owner/repo --limit 5
+gh release view v1.2.3 --repo owner/repo
+```
+
+Use **`gh api`** when you need endpoints not wrapped by a subcommand.
+
+## JSON and automation
+
+Most commands support **`--json`**; combine with **`--jq`** for scripts and summaries:
+
+```bash
+gh pr list --repo owner/repo --state merged --json number,title,mergedAt --jq '.[] | "\(.number)\t\(.title)"'
+```
+
+## Install `gh` (if missing)
+
+- macOS: `brew install gh`
+- Debian/Ubuntu: see [official install docs](https://github.com/cli/cli#installation) for apt and other packages.

package/skills/github-cli/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: github-cli
+description: "Interact with GitHub and CI systems through the gh CLI."
+metadata: {"xbot":{"triggers":["github","git","pr","issue","repo"],"requires":{"bins":["gh"]}}}
+---
+
+# GitHub CLI
+
+Use the `gh` CLI for GitHub issues, pull requests, workflow runs, and CI logs.
+
+## Typical Commands
+
+Check PR checks:
+
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List workflow runs:
+
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+Inspect failed workflow logs:
+
+```bash
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+## Guidance
+
+- Prefer `--json` and `--jq` for structured output.
+- Use repository-qualified commands when not already in the target repository.
+- Summarize failures by root cause, not just by step name.

package/skills/memory/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: memory
+description: "Two-layer workspace memory, automatic session consolidation, and how to search the history log."
+always: true
+metadata: {"xbot":{"description":"Long-term MEMORY.md vs append-only HISTORY.md; when to write; consolidation; grep recall.","always":true,"emoji":"🧠","triggers":["memory","history","recall","consolidate","remember"]}}
+---
+
+# Memory
+
+xbot keeps project memory under the configured workspace, not at the repository root by itself. Paths are relative to that workspace:
+
+- **`.xbot/memory/MEMORY.md`** — Curated long-term context (preferences, architecture, durable decisions). Loaded into the agent context (often via topic slices), size-limited by `agents.defaults.memoryMaxBytes`.
+- **`.xbot/memory/HISTORY.md`** — Append-only log of consolidation and archived conversation chunks. **Not** treated as active context; search it when you need to recover past events or details.
+
+## When to write to MEMORY.md
+
+Update long-term memory when something should survive future sessions:
+
+- Stable user preferences or standing requests
+- Project facts: architecture, conventions, build/test commands, env constraints
+- Decisions that will matter after a session reset or channel switch
+- Durable summaries worth recalling (see the `memory-entry-writer` skill for structured entries)
+
+Avoid pasting full transcripts, raw logs, or ephemeral debugging notes into `MEMORY.md`. Put recoverable-but-not-evergreen detail in `HISTORY.md` (via consolidation) or leave it in the chat.
+
+## When to search HISTORY.md
+
+Use `HISTORY.md` when:
+
+- You need a prior experiment, conclusion, or dated event
+- The user asks “what did we do before?” and it is not in `MEMORY.md`
+- You are debugging memory drift and want to see what was consolidated
+
+## Auto-consolidation
+
+When the session grows large relative to the model context window, xbot **automatically** consolidates older turns:
+
+1. **Preferred path:** The runtime asks the model to summarize a chunk of conversation. A summary is appended to `HISTORY.md`, and an optional short update can be appended to `MEMORY.md` as a consolidation entry.
+2. **Fallback:** If consolidation fails repeatedly, raw message text is archived into `HISTORY.md` in chunks until usage drops back near a safe threshold (roughly three quarters of the configured context budget).
+
+You do not need to trigger consolidation manually. Session commands like `clear` / `new` reset the chat thread; `HISTORY.md` may be reset depending on product behavior—check current docs if that matters for your workflow.
+
+## Grep strategies for HISTORY.md
+
+Pick a strategy based on file size:
+
+- **Small files:** Read the file or a section, then filter mentally.
+- **Large or old logs:** Use the shell from the workspace root so paths resolve.
+
+Examples (macOS/Linux):
+
+```bash
+# Case-insensitive, show line numbers
+grep -ni "keyword" .xbot/memory/HISTORY.md
+
+# Last N matching lines
+grep -i "deploy" .xbot/memory/HISTORY.md | tail -n 30
+
+# Ripgrep: fast, respects .gitignore unless you pass --no-ignore
+rg -n "pattern" .xbot/memory/HISTORY.md
+```
+
+Windows (cmd): `findstr /i "keyword" .xbot\memory\HISTORY.md`
+
+Prefer **narrow patterns** (component names, ticket IDs, error strings) over single common words to avoid noise.
+
+## Relation to other skills
+
+- **`memory-hygiene`** — Day-to-day rules for keeping memory tidy.
+- **`memory-entry-writer`** — Structured writes into `MEMORY.md` for tasks and explicit memorize requests.

package/skills/memory-entry-writer/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: memory-entry-writer
+description: "Summarize durable memory entries for MEMORY.md after task completion or explicit memorize requests."
+metadata: {"xbot":{"triggers":["memory","remember","memorize","save"]}}
+---
+
+# Memory Entry Writer
+
+Use this skill when converting raw task output or user-provided durable facts into a compact `memory/MEMORY.md` entry.
+
+## Output Shape
+
+Return JSON only:
+
+```json
+{"title":"...","summary":"...","attention_points":["..."]}
+```
+
+## Rules
+
+- `title`: plain text, short, specific, no markdown, under 80 characters
+- `summary`: plain text, 1-2 short sentences, under 240 characters
+- `attention_points`: short durable cautions, follow-ups, or constraints; use `[]` when empty
+- Keep only durable facts worth remembering across sessions
+- Do not copy code blocks, long quotes, raw logs, transcript filler, or markdown headings
+- Prefer the repository, workflow, bug, decision, or user preference that will matter later

package/skills/memory-hygiene/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: memory-hygiene
+description: "Always-on guidance for maintaining durable workspace memory and searching historical context."
+metadata: {"xbot":{"always":true,"triggers":["memory","cleanup","consolidate","prune"]}}
+---
+
+# Memory Hygiene
+
+Use this guidance in every workspace.
+
+## Two-Layer Memory
+
+- `memory/MEMORY.md` is active long-term context. Keep it concise and curated.
+- `memory/HISTORY.md` is an append-only log for later search. It is not active context.
+
+## Update MEMORY.md When
+
+- the user states a stable preference
+- you discover a durable project fact or architecture rule
+- a decision will matter in later sessions
+- a recurring process or operational constraint becomes clear
+
+## Search HISTORY.md When
+
+- you need to recall prior events, experiments, or earlier conclusions
+- you suspect a detail was discussed before but is not durable enough for `MEMORY.md`
+- you want to recover context after a session reset
+
+## Practical Rules
+
+1. Keep `MEMORY.md` short and structured.
+2. Do not dump full transcripts or raw logs into long-term memory.
+3. Promote durable facts from `HISTORY.md` into `MEMORY.md` when they become important.
+4. Prefer updating memory immediately after discovering durable context rather than waiting until the end.

package/skills/project-context/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: project-context
+description: "Workspace template for project-specific architecture, commands, and conventions."
+metadata: {"xbot":{"triggers":["project","context","architecture","overview"]}}
+---
+
+# Project Context Template
+
+Fill this skill with repository-specific details that should be easy for the agent to load.
+
+## Suggested Content
+
+- architecture overview
+- key directories and ownership
+- build/test/lint commands
+- deployment or release flow
+- integration caveats
+
+## Guidance
+
+- Prefer concise bullets over large prose blocks.
+- Keep this file updated when the project structure changes.
+- Mirror durable facts into `memory/MEMORY.md` when they should remain active all the time.