@agentshouse/skills 0.0.0-stage → 0.1.0-c6411c39c6d0f

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# `@agentshouse/skills`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Skills agents.house serves its agents, and the texts its agents read.
+
+- `set/` holds one directory per Skill, each with its `SKILL.md`: every engineering and
+  productivity skill of [mattpocock/skills](https://github.com/mattpocock/skills) but its setup
+  skill and `wizard`, file for file beside upstream's `LICENSE`. `upstream.json` names the
+  upstream commit, its date and the skills taken from it.
+- `how-we-work.md` is the How-we-work document's text, and `how-we-work-earlier.json` the
+  SHA-256 of every earlier text.
+- `app-guide.json` is the guide to building an App or a Site, and `agent-instructions.json` the
+  lines that open an agent's first prompt.
+
+```ts
+import { HOW_WE_WORK, listSkills, readSkill } from '@agentshouse/skills';
+
+for (const { name } of listSkills()) console.log(name, readSkill(name).length);
+console.log(HOW_WE_WORK);
+```
+
+`agentInstructions(houseRef, copies)` returns the first prompt's lines, `APP_GUIDE` the guide's
+lines and `EARLIER_HOW_WE_WORK_SHA256` the earlier texts' digests.
+
+The skills come from [mattpocock/skills](https://github.com/mattpocock/skills); thank you, Matt
+Pocock.
+
+MIT.

package/agent-instructions.json

@@ -0,0 +1,10 @@
+{
+  "lines": [
+    "From House:",
+    "Work with House through the `house` CLI: run `house --help`, and `house find_command` for House's guides and formats.",
+    "To give the User a file, upload it with `house upload` and link it; for an App, a Site or a website, follow `house find_command '{\"query\":\"app\"}'`. Never start a server.",
+    "Optional per-Room instructions: `/rooms/private/rooms/<handle>/AGENTS.md`.",
+    "For another Agent's help, `send_routine_request`; its mail comes back into this conversation. If an Agent of your User has no Routine to call, write one in the Private Room and `create_routine_access` with your User as its only caller."
+  ],
+  "copies": "House Local copies; before work run `house fetch` and rebase onto `<house-ref>`; after it commit, then `house push`:"
+}

package/app-guide.json

@@ -0,0 +1,346 @@
+{
+  "name": "App",
+  "aliases": [
+    {
+      "act": "sites/create",
+      "text": "site"
+    }
+  ],
+  "words": [
+    "app",
+    "apps",
+    {
+      "act": "sites/create",
+      "text": "site"
+    },
+    {
+      "act": "sites/create",
+      "text": "website"
+    },
+    "web",
+    "ui",
+    "frontend",
+    "html",
+    "build",
+    "create",
+    "new",
+    "make",
+    "deploy",
+    "publish"
+  ],
+  "text": [
+    {
+      "act": "sites/create",
+      "text": "# Build an App or a Site",
+      "without": "# Build an App"
+    },
+    "",
+    {
+      "act": "sites/create",
+      "text": "An App is a web page over your User's Rooms, for your User and whom they share it with (`create_share`); a Site is one at a public address anyone opens without signing in. House serves the built files and gives the page the App runtime, which holds every bound Room in the browser and syncs it with House. There is no server, backend or House API of yours to call.",
+      "without": "An App is a web page over your User's Rooms, for your User and whom they share it with (`create_share`). House serves the built files and gives the page the App runtime, which holds every bound Room in the browser and syncs it with House. There is no server, backend or House API of yours to call."
+    },
+    "",
+    "## Start",
+    "",
+    "- An App with an `a_` reference already exists, even with no release yet, as every App your User makes in the panel does. Clone its `.git` address, `<origin>/app/<app_ref>.git` or its `source_url` in `list_apps`, with `git clone -c 'credential.helper=!kit git-credential' -c user.name=<agent-git-name> -c user.email=<agent-git-email> <address>`, so Git signs in as you and can commit, in every later step too. Run `npm ci`, then publish with `npm run publish`, never with `--name`.",
+    "- Only when no App exists yet, clone `<origin>/app/new.git` the same way: it gives mdui, a minimal App in plain TypeScript with its test and `npm run publish`. Run `npm ci`, then `npm run publish -- --name \"<display name>\"`, which creates the App and prints its address and its `.git` address. Then `git remote set-url origin <that .git address>`; every later `npm run publish` goes there, without `--name`.",
+    {
+      "act": "sites/create",
+      "text": "- A Site starts with `create_site`: `name` is its address name, and the answer's `source_url` is its App's `.git` address to clone the same way. Anything private is an App."
+    },
+    {
+      "act": "sites/create",
+      "text": "- A Site shows the Rooms it published, as `published` names them: creating it publishes its bound Rooms, a release keeps the published data, and later Room edits stay private until `publish_site_data`. A publication whose `state` is `preparing` replaces the shown one once its screenshot is taken; `list_sites` names each Site's newest publication and its `state`, and `publish_site_data` with nothing changed since answers that publication. `unpublish_site` stops serving a Site and keeps it; `republish_site` or `publish_site_data` serves it again."
+    },
+    "- Use any framework and build tool. `npm run build` leaves the whole release in `dist/`: the entry HTML, every file it loads, `app.json` and `schema.yaml`. The entry names files by relative paths (Vite: `base: './'`), carries no inline script and loads nothing from outside the release, so bundle fonts and libraries. A release holds at most <release-files> files and <release-mib> MiB.",
+    "- Your User sees a change only once it is published, so an ask to change an App is an ask to publish it: end every change with a commit and `npm run publish`, which builds, pushes `main` and the build, and prints `published` or the reason House refused. A `git push` of `main` alone publishes nothing and says so. A refused push changes nothing and the previous release keeps running.",
+    "- Without Git, zip the project folder after the build, without `node_modules` and `.env`, `upload` the ZIP to a Room and publish it with `publish_app_zip`.",
+    "- Every page registers `bridge.cooperate` in its entry script before its first draw, as mdui's `main.ts` does, even a page that reads no Room: only then does a page your User has open take each release by itself, with no reload. A page that registers none keeps the release it opened on until it is opened again. A page that draws everything at once and has nothing to type or select registers `bridge.cooperate({ checkpoint() {}, persist() {}, capture: () => scrollY, restore(top) { scrollTo(0, Number(top)); }, ready: () => true, settle() {} })` after `const bridge = houseBridge()`, which keeps its scroll position. Every other page keeps its User's task through the release as the example below does: `checkpoint` waits until the page has drawn, `persist` until its Room Draft writes are done, failing while a field it shows was refused its last write so the release waits, `capture` answers the focused field with its cursor and selection, the scroll position and whatever else it holds outside the address, and `restore` puts them back once the page has drawn again; `node_modules/@agentshouse/app-bridge/docs/families.md` describes each member.",
+    "",
+    "## Data",
+    "",
+    "- Design the Room schema first. Each thing the App shows is one Markdown document in a Room: its frontmatter `type` names its MD type, the rest of its frontmatter holds the fields, and long text goes in `##` sections. `schema.yaml` declares the types (`find_command` \"Schema\").",
+    "- Keep each type in its own folder, such as `tasks/`, and read it by `pathPrefix`: a query naming `types` fails with `unknown-type` while no bound Room declares them.",
+    "- Link types with `reference` fields instead of copying values; a query follows them with `hop` and `backlinks`.",
+    {
+      "act": "sites/create",
+      "text": "- `app.json` `room_slots` names the Rooms the App needs, each with `access` `read` or `write` and the `types` it uses (`find_command` \"App manifest\"). Bind Rooms with `set_app_bindings`, a Site's with `set_site_bindings`; App code cannot bind and reaches only bound Rooms, so it opens `bridge.ceremony('/bind/<app_ref>?slot=<name>')`, the House page where your User binds Rooms and connects account slots, which returns to the App.",
+      "without": "- `app.json` `room_slots` names the Rooms the App needs, each with `access` `read` or `write` and the `types` it uses (`find_command` \"App manifest\"). Bind Rooms with `set_app_bindings`; App code cannot bind and reaches only bound Rooms, so it opens `bridge.ceremony('/bind/<app_ref>?slot=<name>')`, the House page where your User binds Rooms and connects account slots, which returns to the App."
+    },
+    "- A bound Room must hold each slot type identically in its own `settings/schema.yaml`, beside any other types, or your User is warned. Write it with `edit` before binding; `create_room` makes a new Room.",
+    "- Read an existing Room's `settings/schema.yaml` before inventing types. Two Apps over one schema are two interfaces over the same data, and your User's Agents read and write those documents too.",
+    "- What no browser can do, such as acting when documents change or at a set time, is a Trigger (`create_trigger`) that notifies or starts a Routine on an Agent; what it writes reaches the App at once.",
+    "",
+    "## Local first",
+    "",
+    "- The runtime holds every bound Room on the device and streams in every change, from any device, App or Agent. `query`, `search` and `observe` answer from the device and never wait on the network.",
+    "- Draw from `observe` at once, with no loading spinner for Room data and no request of your own; an observation hears each later change by itself, so never poll, refetch or subscribe to House. An answer is `{ pending }` while a Room it reads has not reached this device or been prepared on it, or the search index has not: draw the page without those documents, and keep the empty state for a complete answer that has none.",
+    "- Write optimistically: write a Room Draft, then `save`. The change shows in every query at once as a Pending Change and reaches House when it can. `save` refuses at once, with its `code`, a change that is `stale`, `changed-underneath` or against the schema: say so and keep the form.",
+    "- Show what the runtime reports: `observe('queue', room)` lists changes House has not confirmed yet, and `observe('sync-status')`'s `attentionRequired` lists each change House refused, returned as a Room Draft with why, to save again or discard.",
+    "- Keep what the User types in the Room Draft (`roomDraft.write`) as they type; it survives a new release replacing the page, a reload and another tab. Draw a form again only when its page changes, never on a streamed change.",
+    "- A document has one Room Draft, shared by every tab and App, and `save` takes all of it. A write replaces every part and names the revision it read, so write onto the parts it holds; one from an older revision answers `stale` with the current Room Draft: show that one. A field part names as its `base` the value the page showed, `{ value }`, or `null` when the document has no such field.",
+    "- Save a change the User does not type, such as a checkbox, with `saveParts(room, [{ path, parts }])`: it writes no Room Draft, so the one another tab holds stays.",
+    "- Offline, all of this works and saves wait. `bridge.onStatus` reports `offline`; say so quietly.",
+    "- A Room your User reads by Online Read locks once the browser has been offline 2 minutes, and from the moment it opens until House confirms the access. While it is locked, `rooms` lists it `locked: true`, a query or search that does not name it leaves it out, one naming it answers `{ pending }` with `awaits: 'unlock'`, and every other read and write naming it, `save` included, answers the code `room-locked` and keeps nothing. Draw it as locked until it unlocks and keep what the User types in the page; what was saved before stays and is sent then.",
+    "- An outside service is reached only at the origins `app.json` lists in `external_origins`; a keyed one through an `account_slots` entry and `bridge.callExternal` naming the slot and a bound Room that connects it, where House adds the key the page never sees.",
+    "- The page's own storage is a disposable cache, the Room the only durable home of the App's data; handle any code or value you do not know through `code` and `retryable`, which every refusal and failure carries.",
+    "- React: `useObserve` and `useSave` from `@agentshouse/mdruntime/react`. react-admin and Refine: the data providers of `@agentshouse/mdruntime-families`. The whole client is described in `node_modules/@agentshouse/mdruntime/AGENTS.md`.",
+    "",
+    "## Example: tasks",
+    "",
+    "`schema.yaml`, also written into the Room's `settings/schema.yaml`:",
+    "",
+    "```yaml",
+    "task:",
+    "  properties:",
+    "    title: { type: string }",
+    "    done: { type: boolean }",
+    "  required: [title, done]",
+    "```",
+    "",
+    "`app.json`, then `set_app_bindings` with slot `tasks`:",
+    "",
+    "```json",
+    "{ \"entry\": \"index.html\", \"room_slots\": [{ \"name\": \"tasks\", \"access\": \"write\", \"types\": [\"task\"] }] }",
+    "```",
+    "",
+    "`main.ts`: a list at `/` and a form at each task's own address, keeping every rule above.",
+    "",
+    "```ts",
+    "import { houseBridge } from '@agentshouse/app-bridge';",
+    "",
+    "type Task = { top: number; field: string | null; start: number | null; end: number | null };",
+    "",
+    "const bridge = houseBridge();",
+    "let shown!: () => void;",
+    "const showing = new Promise<void>((resolve) => (shown = resolve));",
+    "let writing: Promise<unknown> = Promise.resolve();",
+    "const unsaved = new Set<HTMLInputElement>();",
+    "bridge.cooperate({",
+    "  checkpoint: () => showing,",
+    "  async persist() {",
+    "    await writing;",
+    "    if ([...unsaved].some((title) => title.isConnected)) throw new Error('unsaved');",
+    "  },",
+    "  capture(): Task {",
+    "    const at = document.activeElement;",
+    "    const field = at instanceof HTMLInputElement && at.selectionStart !== null ? at : null;",
+    "    return { top: scrollY, field: field?.ariaLabel ?? null, start: field?.selectionStart ?? null, end: field?.selectionEnd ?? null };",
+    "  },",
+    "  async restore(task) {",
+    "    await showing;",
+    "    const held = task as Task | null;",
+    "    if (held === null) return;",
+    "    const field = Array.from(document.querySelectorAll('input')).find((input) => held.field !== null && input.ariaLabel === held.field);",
+    "    field?.focus({ preventScroll: true });",
+    "    field?.setSelectionRange(held.start, held.end);",
+    "    scrollTo(0, held.top);",
+    "  },",
+    "  ready: () => true,",
+    "  settle() {},",
+    "});",
+    "const runtime = await bridge.runtime;",
+    "const rooms = await runtime.observe('rooms');",
+    "const sync = await runtime.observe('sync-status');",
+    "const drafts = await runtime.observe('room-drafts');",
+    "const tasks = await runtime.observe('query', {",
+    "  pathPrefix: 'tasks',",
+    "  select: { fields: ['/title', '/done'] },",
+    "  orderBy: [{ by: { field: '/title' } }],",
+    "});",
+    "const main = document.querySelector('main')!;",
+    "const list = document.createElement('div');",
+    "const note = document.createElement('p');",
+    "type Parts = Parameters<typeof runtime.roomDraft.write>[3];",
+    "type Draft = Awaited<ReturnType<typeof runtime.roomDraft.read>>;",
+    "let drawn: string | undefined;",
+    "",
+    "async function write(room: string, path: string, held: Draft, parts: Parts) {",
+    "  const { file: _file, ...kept } = { ...held?.parts };",
+    "  const onto = { ...kept, ...parts, fields: { ...kept.fields, ...parts.fields } };",
+    "  const written = await runtime.roomDraft.write(room, path, held?.revision ?? null, onto);",
+    "  return written.outcome === 'written' ? { draft: written.roomDraft, stale: false } : { draft: written.current, stale: true };",
+    "}",
+    "",
+    "async function save(room: string, draft: Draft): Promise<boolean> {",
+    "  const saved = draft === null ? null : await runtime.save(room, [{ path: draft.path, revision: draft.revision }]);",
+    "  note.textContent = saved?.outcome === 'saved' ? '' : `Not saved: ${saved?.code ?? 'stale'}.`;",
+    "  return saved?.outcome === 'saved';",
+    "}",
+    "",
+    "function queued<T>(work: () => Promise<T>): Promise<T | null> {",
+    "  const done = writing.then(work).catch((error: { code?: unknown }) => {",
+    "    note.textContent = `Not saved: ${String(error.code)}.`;",
+    "    return null;",
+    "  });",
+    "  writing = done;",
+    "  return done;",
+    "}",
+    "",
+    "function taskCreation(draft: Draft) {",
+    "  const creation = draft?.parts.creation;",
+    "  return creation !== undefined && 'type' in creation && creation.type === 'task' ? creation : undefined;",
+    "}",
+    "",
+    "function titleOf(draft: Draft): unknown {",
+    "  return draft?.parts.fields?.title?.value ?? taskCreation(draft)?.fields.title;",
+    "}",
+    "",
+    "function el<K extends keyof HTMLElementTagNameMap>(tag: K, props: object, ...children: (Node | string)[]) {",
+    "  const node = Object.assign(document.createElement(tag), props);",
+    "  node.append(...children);",
+    "  return node;",
+    "}",
+    "",
+    "function titleForm(action: string, room: string, path: () => string, shown: unknown, parts: (title: string, held: Draft) => Parts, done: (title: HTMLInputElement) => void) {",
+    "  let held = drafts.current().find((draft) => draft.room === room && draft.path === path()) ?? null;",
+    "  const title = el('input', { value: String(titleOf(held) ?? shown), required: true, ariaLabel: 'Title' });",
+    "  const keep = () =>",
+    "    queued(async () => {",
+    "      unsaved.add(title);",
+    "      const written = await write(room, path(), held, parts(title.value, held));",
+    "      unsaved.delete(title);",
+    "      held = written.draft;",
+    "      if (written.stale) title.value = String(titleOf(held) ?? shown);",
+    "      return written.stale;",
+    "    });",
+    "  title.oninput = () => void keep();",
+    "  const form = el('form', {}, title, el('button', {}, action));",
+    "  form.onsubmit = async (event) => {",
+    "    event.preventDefault();",
+    "    const stale = await keep();",
+    "    if (stale === null) return;",
+    "    if (stale) return void (note.textContent = 'Not saved: stale.');",
+    "    if (!(await save(room, held))) return;",
+    "    held = null;",
+    "    done(title);",
+    "  };",
+    "  return form;",
+    "}",
+    "",
+    "function editForm(room: string, path: string, shown: unknown) {",
+    "  const parts = (title: string): Parts => ({ fields: { title: { value: title, base: { value: shown } } } });",
+    "  return titleForm('Save', room, () => path, shown, parts, () => void bridge.push('/'));",
+    "}",
+    "",
+    "function addForm(room: string) {",
+    "  const parts = (title: string, held: Draft): Parts => {",
+    "    const kept = taskCreation(held) ?? { type: 'task', fields: { done: false }, sections: {} };",
+    "    return { creation: { ...kept, fields: { ...kept.fields, title } } };",
+    "  };",
+    "  const adding = drafts.current().find((draft) => draft.room === room && draft.path.startsWith('tasks/') && taskCreation(draft));",
+    "  let path = adding?.path ?? `tasks/${crypto.randomUUID()}.md`;",
+    "  return titleForm('Add', room, () => path, '', parts, (title) => {",
+    "    title.value = '';",
+    "    path = `tasks/${crypto.randomUUID()}.md`;",
+    "  });",
+    "}",
+    "",
+    "async function toggle(room: string, path: string, done: boolean): Promise<void> {",
+    "  const parts = { fields: { done: { value: !done, base: { value: done } } } };",
+    "  const saved = await runtime.saveParts(room, [{ path, parts }]);",
+    "  note.textContent = saved.outcome === 'saved' ? '' : `Not saved: ${saved.code}.`;",
+    "  draw();",
+    "}",
+    "",
+    "function draw(): void {",
+    "  const room = rooms.current()[0];",
+    "  const answer = tasks.current();",
+    "  const held = 'pending' in answer ? [] : answer.documents;",
+    "  const open = held.find((task) => `/${task.path}` === bridge.address());",
+    "  const page = room === undefined ? '' : `${room.locator}/${open?.path ?? ''}`;",
+    "  if (page !== drawn) {",
+    "    drawn = page;",
+    "    note.textContent = '';",
+    "    if (room === undefined) main.replaceChildren('This App has no Room yet.');",
+    "    else if (open !== undefined) main.replaceChildren(editForm(open.room, open.path, open.fields!.title), note);",
+    "    else main.replaceChildren(list, addForm(room.locator), note);",
+    "  }",
+    "  if (!('pending' in answer)) shown();",
+    "  if (room === undefined) return;",
+    "  const refused = new Set(sync.current().attentionRequired.flatMap((entry) => ('path' in entry ? [entry.path] : [])));",
+    "  const rows = held.map((task) => {",
+    "    const done = task.fields!.done === true;",
+    "    const box = el('input', { type: 'checkbox', checked: done, ariaLabel: 'Done' });",
+    "    box.onchange = () => void queued(() => toggle(task.room, task.path, done));",
+    "    const link = el('a', { href: task.path }, String(task.fields!.title));",
+    "    link.onclick = (event) => {",
+    "      event.preventDefault();",
+    "      void bridge.push(`/${task.path}`);",
+    "    };",
+    "    return el('li', {}, box, link, refused.has(task.path) ? ' (refused)' : '');",
+    "  });",
+    "  const empty = 'pending' in answer ? '' : 'No tasks yet. Add the first one.';",
+    "  list.replaceChildren(rows.length > 0 ? el('ul', {}, ...rows) : empty);",
+    "}",
+    "",
+    "for (const observed of [rooms, sync, tasks]) observed.subscribe(draw);",
+    "bridge.onAddress(draw);",
+    "draw();",
+    "```",
+    "",
+    "## The page",
+    "",
+    "- The App draws everything; House draws nothing around it. Set the tab's title with `bridge.setTab({ title })`.",
+    "- The address bar is the shell's, not your page's: read your place from `bridge.address()` and `bridge.onAddress`, and move with `bridge.push` or `bridge.replace`, so Back, Forward, reload and a shared link keep it. Keep the open item, tab, filter and search in the address. Addresses under `/render`, `/info` and `/tab-icon` are House's.",
+    "- Mobile first: lay out from 360 pixels wide up, with no action behind hover alone.",
+    "- Every control works from the keyboard, with visible focus and a label.",
+    "- An empty list says what it will hold and invites the first document.",
+    "- Long names truncate with an ellipsis and show in full on hover.",
+    "- The element is the link: a row, card or name opens its item; no \"Open\" buttons.",
+    "- Offer installation yourself: `bridge.install()` from a click shows the browser's prompt, or answers `manual` where you show how.",
+    "",
+    {
+      "act": "sites/create",
+      "text": "## Sites"
+    },
+    {
+      "act": "sites/create",
+      "text": ""
+    },
+    {
+      "act": "sites/create",
+      "text": "- A Site is public: anyone opens it, nobody signs in, and every visitor reads its bound Rooms, which must be your User's own and never the Private Room."
+    },
+    {
+      "act": "sites/create",
+      "text": "- Everything it shows lives as documents in its Room; put its demo data there, never in code."
+    },
+    {
+      "act": "sites/create",
+      "text": "- A visitor's edits stay in their browser and never reach House: write them with `save` as an App does."
+    },
+    {
+      "act": "sites/create",
+      "text": "- To receive messages from visitors, name an Intake Room with `set_site_intake_room` and send each with `runtime.call('submit', { content })`, online only."
+    },
+    {
+      "act": "sites/create",
+      "text": "- `describe_site` sets the title and description search engines show."
+    },
+    {
+      "act": "sites/create",
+      "text": ""
+    },
+    "## Verify",
+    "",
+    "Before `npm run publish`:",
+    "",
+    "- `npm test` passes against the newest `@agentshouse/app-bridge` and `@agentshouse/mdruntime` (`npm install <name>@latest`), since every page gets House's newest runtime. Keep mdui's test: it runs the built page on `createMemoryAdapter` from `@agentshouse/mdruntime/memory` and `createHouseBridgeTestHost` from `@agentshouse/app-bridge/test-host`, with no House.",
+    "- Every slot type is in `schema.yaml` exactly as in the bound Room's `settings/schema.yaml`.",
+    "- The entry script registers `bridge.cooperate` before its first draw.",
+    "- The page works 360 pixels wide, offline, and reloaded at a deep address.",
+    "",
+    "After it:",
+    "",
+    "- `list_apps` names the App's `published_release`, whose `revision` is the `main` commit it was built from; a clone, a fetch and `git ls-remote` see `main` alone.",
+    "- Bind the Room once with `set_app_bindings`.",
+    {
+      "act": "sites/create",
+      "text": "- See it yourself: sign your own browser in with `create_sign_in_code`, then open the App's url. A Site needs none.",
+      "without": "- See it yourself: sign your own browser in with `create_sign_in_code`, then open the App's url."
+    },
+    "- Give your User its address. An open page that registers `bridge.cooperate` takes each release by itself; nothing asks them to update."
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export type GuideLine = string | {
+    readonly act: string;
+    readonly text: string;
+    readonly without?: string;
+};
+export interface Guide {
+    readonly name: string;
+    readonly aliases: readonly GuideLine[];
+    readonly words: readonly GuideLine[];
+    readonly text: readonly GuideLine[];
+}
+export interface Skill {
+    readonly name: string;
+    readonly directory: string;
+}
+export interface SkillFile {
+    readonly path: string;
+    readonly content: string;
+}
+export declare const HOW_WE_WORK: string;
+export declare const EARLIER_HOW_WE_WORK_SHA256: readonly string[];
+export declare const APP_GUIDE: Guide;
+export declare function agentInstructions(houseRef: string, copies: readonly string[]): string[];
+export declare function listSkills(): readonly Skill[];
+export declare function readSkill(name: string): readonly SkillFile[];

package/dist/index.js

@@ -0,0 +1,46 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const PACKAGE = fileURLToPath(new URL('..', import.meta.url));
+const SET = join(PACKAGE, 'set');
+const ENTRY = 'SKILL.md';
+const REF_PLACEHOLDER = '<house-ref>';
+function packaged(name) {
+    return readFileSync(join(PACKAGE, name), 'utf8');
+}
+export const HOW_WE_WORK = packaged('how-we-work.md');
+export const EARLIER_HOW_WE_WORK_SHA256 = JSON.parse(packaged('how-we-work-earlier.json'));
+export const APP_GUIDE = JSON.parse(packaged('app-guide.json'));
+const INSTRUCTIONS = JSON.parse(packaged('agent-instructions.json'));
+export function agentInstructions(houseRef, copies) {
+    if (copies.length === 0)
+        return [...INSTRUCTIONS.lines];
+    return [
+        ...INSTRUCTIONS.lines,
+        INSTRUCTIONS.copies.replaceAll(REF_PLACEHOLDER, houseRef),
+        ...copies,
+    ];
+}
+export function listSkills() {
+    return readdirSync(SET, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+        .map((name) => ({ name, directory: join(SET, name) }));
+}
+function entryFirst(left, right) {
+    if (left === ENTRY || right === ENTRY)
+        return left === ENTRY ? -1 : 1;
+    return left < right ? -1 : 1;
+}
+export function readSkill(name) {
+    const skill = listSkills().find((listed) => listed.name === name);
+    if (skill === undefined)
+        throw new Error(`no Skill is named ${name}`);
+    return readdirSync(skill.directory, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(skill.directory, join(entry.parentPath, entry.name)))
+        .map((path) => path.split(sep).join('/'))
+        .sort(entryFirst)
+        .map((path) => ({ path, content: readFileSync(join(skill.directory, path), 'utf8') }));
+}

package/how-we-work-earlier.json

@@ -0,0 +1,6 @@
+[
+  "ae4dda60da7b174f22dc5fa9bf07fc27c25864932a74230de4f9f509ddd91f41",
+  "0bdcd43e1603ba6673a3cae56d70bbf90657cbeefd124e91a47be2ca1cbd6c93",
+  "4106a87ec66da6f7b2a10e74d18e6559d68d5f4fe7415dae68f5c7bdb9081968",
+  "ac814a2197038f037b657bb719340395f89f319ac9fcdd386629c3fe2cec68f1"
+]

package/how-we-work.md

@@ -0,0 +1,33 @@
+# How we work
+
+A Room is where information people share is kept; it is not the place for
+private information. Work goes into the Room it belongs to, or the First Room
+when none is named.
+
+Every House answer carries the `url` of what it names; send the User that link.
+
+The skills are already set up; never run `setup-matt-pocock-skills`.
+
+## Where skill output goes
+
+- Glossary (`GLOSSARY.md`): `glossary.md`
+- Decisions (ADRs): `decisions/NNNN-<slug>.md`
+- Plan (spec): `projects/<name>/plan.md`
+- Tasks (tickets): `projects/<name>/tasks/NN-<slug>.md`, with a
+  `Status:` line (`needs-triage`, `needs-info`, `ready-for-agent`,
+  `ready-for-human`, `wontfix`, or `done` once implemented), a
+  `Category:` line (`bug`, `enhancement`), a `Blocked by:` line and comments
+  under `## Comments`; triage takes no pull requests
+- Rejected requests (triage): `out-of-scope/<concept>.md`
+- Implementation notes (implement-spec): `projects/<name>/notes/`
+- PR bodies (pr): `projects/<name>/prs/<branch>.md`
+- Map (Wayfinding): `projects/<name>/map.md`, its tasks under
+  `tasks/` with `Type:`, `Status: claimed|resolved` and `Blocked by:` lines
+- Research: `research/<slug>.md`
+- Architecture reports (improve-codebase-architecture): `architecture/<slug>.html`
+- Handoffs: `handoffs/<slug>.md`
+- Questionnaires: `questionnaires/<slug>.md`
+- Retrospectives (retro): `retros/<date>-<slug>.md`
+- Wizards: `wizards/<slug>.sh`; the values they capture stay out of the Room
+- Learning: `learning/<topic>/`
+- Prototype: one HTML file with every variant on one page.

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@agentshouse/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-c6411c39c6d0f",
+  "description": "The Skills agents.house serves its agents, upstream's verbatim beside its own, and the texts its agents read: the How-we-work document, the App guide and the Agent instructions",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.21.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "set",
+    "upstream.json",
+    "how-we-work.md",
+    "how-we-work-earlier.json",
+    "app-guide.json",
+    "agent-instructions.json",
+    "README.md"
+  ]
+}

package/set/ask-matt/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/set/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session: the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make: continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session (the exploration, the decisions, the dead ends) disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal: the old session stays resumable.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `/handoff` buys is **portability**: a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop: this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source**: the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective: each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.