@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/src/modules/write-access/__tests__/write-access.test.ts

@@ -47,6 +47,12 @@ describe('isAlwaysWritable', () => {
     ['POST', '/api/workspace/w1/access/batch'],
     ['POST', '/api/workspace/w1/workflow/locks/heartbeat'],
     ['POST', '/api/events/s1/focus'],
+    // The Atlassian connector's VIEW mint: it signs a token, changes nothing.
+    ['POST', '/api/embed/token'],
+    // The embed's lock signals, like the app's heartbeat: a held lock kept
+    // or let go, no content changed.
+    ['POST', '/api/embed/heartbeat'],
+    ['POST', '/api/embed/cancel'],
   ])('lets %s %s through', (method, path) => {
     expect(isAlwaysWritable(method, path)).toBe(true);
   });
@@ -59,6 +65,13 @@ describe('isAlwaysWritable', () => {
     ['POST', '/api/workspace/w1/workflow/locks'],
     ['POST', '/api/plugins'],
     ['POST', '/api/admin/groups'],
+    // The embed's own edits stay refused like every other write — taking the
+    // lock included, since it is the first step of a save.
+    ['POST', '/api/embed/save'],
+    ['POST', '/api/embed/propose'],
+    ['POST', '/api/embed/lock'],
+    ['POST', '/api/embed/token/extra'],
+    ['POST', '/api/embed/heartbeat/extra'],
     // A look-alike of an allowed path is not that path.
     ['POST', '/api/admin/accountsx'],
     ['POST', '/api/workspace/w1/access/batch/extra'],

package/src/modules/write-access/write-access.ts

@@ -48,6 +48,12 @@ const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
  *  - Account administration: the way an admin brings the number of people
  *    down. Erasing an account with `removeFromAccess` commits to the
  *    knowledge base, and that commit is part of the same act.
+ *  - The embed mint: `POST /api/embed/token` signs a short-lived VIEW
+ *    token for the Atlassian connector and changes nothing; the embed's
+ *    own edit routes stay refused. Its lock heartbeat and cancel stay open
+ *    for the same reason the app's heartbeat does: a held lock is kept or
+ *    let go, and no content changes — refusing them would have an editor
+ *    read the refusal as "your access was withdrawn".
  *  - The tool surface: every tool call is judged by the tool layer itself,
  *    which knows a read tool from a write tool (see `toolHandler`); the MCP
  *    endpoint only relays to it.
@@ -76,6 +82,9 @@ const ALWAYS_WRITABLE: readonly RegExp[] = [
   /^\/api\/workspace\/[^/]+\/workflow\/locks\/heartbeat$/,
   /^\/api\/events\/[^/]+\/focus$/,
   /^\/api\/tools\/preview$/,
+  /^\/api\/embed\/token$/,
+  /^\/api\/embed\/heartbeat$/,
+  /^\/api\/embed\/cancel$/,
 ];
 
 /**

package/src/shared/domain-errors.ts

@@ -108,24 +108,53 @@ export class PushNeedsAgentResolutionError extends WorkflowDomainError {
     readonly path: string,
     readonly originalDetail: string,
     readonly recoveryDetail: string,
+    /**
+     * Why the push did not land. `diverged`: the remote moved and the
+     * cooperative rebase could not reconcile. `refused`: the host turned the
+     * push away for any other reason (an outage, credentials, a dropped
+     * connection) — nothing to reconcile, the next push of the branch carries
+     * the commits. The opening clause is the same either way.
+     */
+    readonly cause: 'diverged' | 'refused' = 'diverged',
   ) {
     super(
       `Saved locally on "${branch}" but couldn't share with the team automatically — ` +
-        `the remote diverged on "${path}" and the cooperative rebase couldn't reconcile. ` +
-        `The agent will resolve this.`,
+        (cause === 'refused'
+          ? `the repository host refused the push; the next save on this branch will try sharing it again.`
+          : `the remote diverged on "${path}" and the cooperative rebase couldn't reconcile. ` +
+            `The agent will resolve this.`),
       409,
-      {
-        kind: 'push-needs-resolution',
-        branch,
-        path,
-        originalDetail,
-        recoveryDetail,
-      },
+      // The two details are raw git output — stderr can quote a credentialed
+      // URL, server paths, the host's own error page. They stay on the error
+      // for the server log and never enter the payload the browser receives.
+      { kind: 'push-needs-resolution', branch, path },
     );
     this.name = 'PushNeedsAgentResolutionError';
   }
 }
 
+/**
+ * The repository host refused to delete a branch (an outage, a protection
+ * rule, a dropped connection). Deletion pushes FIRST and deletes locally only
+ * once the host agreed, so the branch is still there — locally and remotely —
+ * and the person can try again later. Unlike a refused write there is nothing
+ * to keep "saved locally": a deleted branch has no later push to carry it.
+ *
+ * `detail` is the raw git failure, for the server log only; it never enters
+ * the message or the payload.
+ */
+export class BranchDeleteRefusedError extends WorkflowDomainError {
+  readonly kind = 'branch-delete-refused' as const;
+  constructor(readonly branchName: string, readonly detail: string) {
+    super(
+      `The repository host refused to delete "${branchName}"; it is still there. Try again later.`,
+      409,
+      { kind: 'branch-delete-refused', branchName },
+    );
+    this.name = 'BranchDeleteRefusedError';
+  }
+}
+
 /**
  * Refreshing a workspace from origin (`GitService.pull`) hit a rebase
  * conflict: the workspace carries local commits origin doesn't have, origin
@@ -221,8 +250,18 @@ const STRINGIFIED_ABSENT_VALUES = new Set(['undefined', 'null']);
  * nothing", which is the one case where naming the branch back is impossible.
  */
 export function assertBranchProvided(branch: unknown): asserts branch is string {
-  if (typeof branch !== 'string' || branch.length === 0) throw new BranchRequiredError();
-  if (STRINGIFIED_ABSENT_VALUES.has(branch)) throw new BranchRequiredError();
+  if (!branchProvided(branch)) throw new BranchRequiredError();
+}
+
+/**
+ * The same question as {@link assertBranchProvided}, answered rather than
+ * thrown — for a caller that must know whether the branch refusal is the one
+ * this call is going to get, without being the one to raise it. The generic
+ * argument check asks it so that refusal keeps coming first.
+ */
+export function branchProvided(branch: unknown): branch is string {
+  if (typeof branch !== 'string' || branch.length === 0) return false;
+  return !STRINGIFIED_ABSENT_VALUES.has(branch);
 }
 
 /**
@@ -245,6 +284,23 @@ export class BranchNotFoundError extends WorkflowDomainError {
   }
 }
 
+/**
+ * A tool that defaults its branch was called without one, and the deployment
+ * has no default branch configured to fall back on. Not `BranchRequiredError`:
+ * the tool's schema says the branch is optional, so "you must pass one" would
+ * misdescribe the call — the caller did nothing wrong, the deployment is not
+ * set up. 503 with kind `default-branch-unset`; passing a branch works.
+ */
+export class DefaultBranchUnsetError extends WorkflowDomainError {
+  readonly kind = 'default-branch-unset' as const;
+  constructor() {
+    super('This deployment has no default branch configured: pass `branch` to name the one to use.', 503, {
+      kind: 'default-branch-unset',
+    });
+    this.name = 'DefaultBranchUnsetError';
+  }
+}
+
 /**
  * The clone's branch no longer exists on origin: the fetch that refreshes
  * `refs/remotes/origin/<branch>` found no such ref. Distinct from an
@@ -330,6 +386,62 @@ export class WorkflowValidationError extends WorkflowDomainError {
   }
 }
 
+/**
+ * An agent's `delete_branch` refused, for a reason a person can act on. The
+ * `reason` is the discriminator a caller branches on; the message says what
+ * to do about it. Nothing was deleted.
+ *
+ * - `open-change-request` (409) — a request is open from or into the branch;
+ *   `number` names it. Withdrawing or declining it is a person's action, in
+ *   the app.
+ * - `unmerged-commits` (409) — `unmergedCommits` commits would be lost;
+ *   `discardUnmerged` is the deliberate way past it.
+ * - `saves-landing` (409) — the branch's checkout still has saves waiting to
+ *   be committed or a file held for editing. Clears itself within seconds.
+ * - `state-unconfirmed` (503) — the shared repository could not be fetched,
+ *   so the branch's current state is unknown.
+ */
+export type BranchDeleteBlockedReason =
+  | 'open-change-request'
+  | 'unmerged-commits'
+  | 'saves-landing'
+  | 'state-unconfirmed';
+
+export class BranchDeleteBlockedError extends WorkflowDomainError {
+  readonly kind = 'branch-delete-blocked' as const;
+  constructor(
+    readonly reason: BranchDeleteBlockedReason,
+    readonly branchName: string,
+    message: string,
+    extra: Record<string, unknown> = {},
+  ) {
+    // `extra` first: it adds detail, and can never contradict the kind,
+    // reason or branch the status and fields above were chosen for.
+    super(message, reason === 'state-unconfirmed' ? 503 : 409, {
+      ...extra,
+      kind: 'branch-delete-blocked',
+      reason,
+      branchName,
+    });
+    this.name = 'BranchDeleteBlockedError';
+  }
+}
+
+/**
+ * The commit an applied change request records is in the clone but is NOT
+ * that request's own merge commit — no second parent (not a merge), no first
+ * parent (a root commit), or a message that does not name the request. A
+ * validation failure like the one above, told apart
+ * because it never mends: a reader may remember it, where a commit the clone
+ * merely does not hold yet must be asked for again after the next fetch.
+ */
+export class AppliedChangeMismatchError extends WorkflowValidationError {
+  constructor(message: string, payload?: Record<string, unknown>) {
+    super(message, payload);
+    this.name = 'AppliedChangeMismatchError';
+  }
+}
+
 /**
  * The next step a missing path always offers, in one sentence.
  *

package/src/shared/git.contract.ts

@@ -70,8 +70,15 @@ export interface GitCredentials {
    * failure here is not the call's failure: git runs with the token in
    * hand, and the host says what it thinks of it. Absent for a credential
    * that does not expire.
+   *
+   * `refused` is the runner reporting that the host just refused the
+   * credential in hand: whatever is held is dead, however much time the
+   * clock says it has left, and a fresh one is asked for now, past whatever
+   * the provider remembers about a recent failure. The failure is thrown to
+   * the caller; what `token` answers afterwards is what the runner judges
+   * by — a credential that could not be replaced is not offered again.
    */
-  prepare?(): Promise<void>;
+  prepare?(opts?: { refused?: boolean }): Promise<void>;
 }
 
 /** The username git is given when a deployment names none. */

package/src/shared/hidden-tools.ts

@@ -0,0 +1,45 @@
+/**
+ * A connected tool Hexis keeps off every agent surface because its input
+ * schema is not valid JSON Schema as its server sent it — and the read port
+ * the surfaces that SHOW that to the server's owner use.
+ *
+ * Here rather than in either module because two of them meet over it: the MCP
+ * proxy finds these when a server's tools are loaded (`modules/mcp`), and the
+ * tool catalog reports them to the people who manage the server
+ * (`modules/tool-manuals`, on the tool page and in `list_tool_setup`). Neither
+ * has any business importing the other.
+ */
+
+/** One connected tool hidden from agents, and why. */
+export interface HiddenTool {
+  /** The manual (the `.tool` or `mcp.json` server) the tool came from, by catalog name. */
+  manual: string;
+  /** The name an agent would have called it by, had it been offered. */
+  name: string;
+  /** JSON Pointer to the place in the input schema that is not valid. */
+  path: string;
+  /** The violation in the validator's own words, e.g. `must be a string`. */
+  reason: string;
+  /** The one sentence every owner-facing surface shows, built once so they cannot drift. */
+  marker: string;
+}
+
+/**
+ * What the owner-facing surfaces read. A deployment that never builds an MCP
+ * surface has nothing to report, so every consumer treats the port as
+ * optional and an absent one as "no tool is hidden".
+ */
+export interface HiddenToolSource {
+  /**
+   * The tools of `manual` currently hidden for an invalid schema, by the
+   * manual's CATALOG name — empty for a healthy server, and empty for a server
+   * whose tools this process has not loaded yet.
+   *
+   * A finding belongs to the SERVER, not to whoever's request loaded it: a
+   * schema is a property of the tool definition, and the people who can get it
+   * fixed are not necessarily the person whose connection saw it. So this is
+   * every finding this process holds for that manual, from whichever callers
+   * have loaded it, each distinct defect once.
+   */
+  hiddenFor(manual: string): HiddenTool[];
+}

package/src/shared/utf8-text.ts

@@ -0,0 +1,21 @@
+import { isUtf8 } from 'node:buffer';
+
+/**
+ * The one rule for "is this text": no NUL byte AND valid UTF-8. A NUL-free
+ * file that does not decode as UTF-8 is still binary — the decode would be
+ * lossy, so text written back could never round-trip the original bytes.
+ * Checked on the raw bytes, so a large binary is refused without allocating
+ * its decoded string first. Every reader that has to decide "text to render
+ * or edit, or bytes to copy as they are" — the fallback text reader, the
+ * access-rule writer, the template seeder, the starter packs — reads the
+ * policy from here, so a file one treats as text another never treats as
+ * bytes.
+ */
+export function isTextBytes(bytes: Buffer): boolean {
+  return !bytes.includes(0) && isUtf8(bytes);
+}
+
+/** The bytes as text when they ARE text by {@link isTextBytes} (BOM kept), else null. */
+export function utf8Text(bytes: Buffer): string | null {
+  return isTextBytes(bytes) ? bytes.toString('utf8') : null;
+}

package/src/tenancy/__tests__/static-tenant-source.test.ts

@@ -11,6 +11,7 @@ const settings: TenantHostSettings = {
   trustProxy: '1',
   workspacesRoot: path.resolve('/srv/hexis/workspaces'),
   kbTemplateDir: '/srv/hexis/template',
+  starterPacksDir: '/srv/hexis/starter-packs',
   gitTimeoutMs: 120_000,
   updateCheckEnabled: false,
   masterKey: 'a-master-key-that-is-long-enough-to-count-as-random',

package/src/tenancy/static-tenant-source.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { resolveDatabaseUrl, type TenantConfig } from '../core-config.js';
 import { DEFAULT_DB_SCHEMA, assertSchemaName } from '../modules/database/connection.js';
 import { DEFAULT_GIT_TIMEOUT_MS } from '../modules/workflow/git/node-git-runner.js';
-import { defaultKbTemplateDir } from '../assets.js';
+import { defaultKbTemplateDir, defaultStarterPacksDir } from '../assets.js';
 import { DEFAULT_GIT_USERNAME } from '../shared/git.contract.js';
 import { deriveTenantSecrets } from './tenant-secrets.js';
 import { loopbackTenantBaseUrl } from './tenant-host.js';
@@ -22,6 +22,7 @@ export interface TenantHostSettings {
   /** Each tenant's workspaces live under `<workspacesRoot>/<slug>`; its backups, spills and caches beside them. */
   readonly workspacesRoot: string;
   readonly kbTemplateDir: string;
+  readonly starterPacksDir: string;
   readonly gitTimeoutMs: number;
   readonly updateCheckEnabled: boolean;
   /** See `tenant-secrets.ts`. */
@@ -169,6 +170,11 @@ export function tenantConfigFrom(record: TenantRecord, settings: TenantHostSetti
     jwtSecret: secrets.jwtSecret,
     secretsEncKey: secrets.secretsEncKey,
     internalTokenSecret: secrets.internalTokenSecret,
+    // No shared-secret mint on a tenant of a host: the Atlassian connector
+    // is pointed at a deployment, not at one knowledge base inside a host,
+    // and a secret derived per tenant would be a credential nobody issued.
+    // The MCP App needs none of it — it mints through the MCP session.
+    embedSharedSecret: '',
     adminEmail,
     adminPassword,
     loginPasswordEnabled,
@@ -182,6 +188,7 @@ export function tenantConfigFrom(record: TenantRecord, settings: TenantHostSetti
     gitUsername,
     gitToken: (record.gitToken ?? '').trim(),
     kbTemplateDir: settings.kbTemplateDir,
+    starterPacksDir: settings.starterPacksDir,
     updateCheckEnabled: settings.updateCheckEnabled,
     allowedEmailDomains,
     trustProxy: settings.trustProxy,
@@ -261,7 +268,7 @@ const MAX_TIMER_MS = 2_147_483_647;
  * The host's settings from the environment: the same variables a
  * single-tenant deployment reads for these facts (`DATABASE_URL` and the
  * `POSTGRES_*` parts, `PORT`, `TRUST_PROXY`, `WORKSPACES_ROOT`,
- * `KB_TEMPLATE_DIR`, `GIT_TIMEOUT_MS`, …), plus the three that only a host
+ * `KB_TEMPLATE_DIR`, `STARTER_PACKS_DIR`, `GIT_TIMEOUT_MS`, …), plus the three that only a host
  * has: `TENANTS_FILE`, `TENANT_MASTER_KEY` and `TENANT_IDLE_MINUTES`.
  */
 export function tenantHostEnv(env: NodeJS.ProcessEnv = process.env): TenantHostEnv {
@@ -286,6 +293,7 @@ export function tenantHostEnv(env: NodeJS.ProcessEnv = process.env): TenantHostE
     trustProxy: (env.TRUST_PROXY || (domain ? '1' : '')).trim(),
     workspacesRoot,
     kbTemplateDir: env.KB_TEMPLATE_DIR || defaultKbTemplateDir(),
+    starterPacksDir: env.STARTER_PACKS_DIR || defaultStarterPacksDir(),
     gitTimeoutMs:
       Number.isFinite(gitTimeout) && gitTimeout > 0 && gitTimeout <= MAX_TIMER_MS ? gitTimeout : DEFAULT_GIT_TIMEOUT_MS,
     updateCheckEnabled: (env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false',

package/starter-packs/README.md

@@ -0,0 +1,103 @@
+# Starter packs
+
+After the first-run storage step, a new knowledge base's admin is asked
+"What does your team do?". Each answer is one folder here: the pages and the
+team plugin it adds to the knowledge base, in one commit on the default branch,
+authored by the admin who chose it. "Skip, I'll start from scratch" adds
+nothing. Either way the choice is recorded (the `starterPack` deployment
+setting) and the question is not asked again.
+
+The code is `src/modules/onboarding/` (`starter-packs.ts` reads and validates
+the packs, `starter-pack.service.ts` applies one).
+
+## Layout
+
+```
+<id>/
+  pack.yaml
+  KnowledgeBase/…          pages
+  Plugins/<plugin-name>/…  a team plugin
+  Skills/…                 shared skills (optional)
+```
+
+`pack.yaml`:
+
+```yaml
+id: sales                # the folder's name: lowercase letters, digits, hyphens
+name: Sales              # the chip's label
+description: One line about what the pack adds.
+order: 2                 # chip order: engineering 1, sales 2, support 3, operations 4, general 99
+firstPagePrompt: |       # replaces the generic "write your first page" request for this team
+  Using our Hexis knowledge base, fill in …
+suggestedPages: [About us, Customers, Pricing, Objections, Glossary]   # named in the agent's first-run note
+```
+
+A folder whose `pack.yaml` is missing or does not validate is skipped with a
+warning in the log; the others are still offered. `none` is reserved for the
+skip.
+
+`KnowledgeBase/`, `Plugins/` and `Skills/` use the default layout's names and
+are written under the names the deployment chose for those folders. Text files
+may use the layout placeholders (`{{knowledgeBaseDir}}`, `{{skillsDir}}`,
+`{{pluginsDir}}` and `{{agentsFile}}`, the agent guide's file name). Anything
+else in a pack folder (like this README) is never copied. Dot-files are never
+copied.
+
+Pages are short tasks rather than finished documents: a heading, a line or two
+of placeholders, and "Ask your agent: _…_". While a page still holds exactly
+what the pack wrote it does not count as written, so the "Write your first
+page" step and the agent's first-run note stay open until someone fills one in.
+
+## Plugins
+
+A plugin uses Hexis's normal plugin layout: `plugin.json` (optional; one is
+written for the folder name when absent), `skills/<skill>/SKILL.md`, and the
+licence and provenance of anything vendored (`LICENSE`, `SOURCE.md`) inside the
+plugin folder, so they travel with the skills. Skill names must be unique
+across all packs.
+
+When the pack is applied, the plugin's `access.md` is the pack's own (if it
+ships one) with the admin who applied it added under `read`, `write` and
+`owner`, the way "Create a plugin" makes a plugin its creator's. Without one,
+the admin gets the access.md "Create a plugin" writes. A plugin whose folder
+(or manifest name) already exists in the knowledge base is left alone entirely.
+
+## Applying
+
+Only paths that do not exist yet are written, judged with every path's lock
+held, so a pack never overwrites a page. All of it lands as one commit through
+the platform's batch write (`LockingFilesystem.writeFiles`), under the write
+rules of the default branch, which an admin passes.
+
+## Your own packs
+
+A distribution can offer its own set by pointing `STARTER_PACKS_DIR` at a
+folder in this format. A folder with no valid pack in it means the question is
+never asked.
+
+## Vendored skills
+
+Most packs carry skills adapted from open-source projects. Each plugin's
+`SOURCE.md` names the repository, the commit and what was changed; its
+`LICENSE` is the project's own. Both ship inside the plugin folder, so the
+licence travels with the skills wherever the plugin is copied. (The generated
+`THIRD-PARTY-NOTICES.md` covers npm dependencies only; vendored content is
+attributed here, in the plugin.)
+
+To refresh a plugin's skills from a newer upstream commit:
+
+1. Clone the upstream repository outside this one, at the commit you want, and
+   record it: `git clone --depth 1 <repo> /tmp/upstream && git -C /tmp/upstream rev-parse HEAD`.
+2. Diff the upstream skills against the commit named in `SOURCE.md`
+   (`git -C /tmp/upstream diff <old-sha> -- <skill folders>` after fetching the
+   old commit) and carry the changes into the adapted files by hand. The
+   adaptation notes in `SOURCE.md` say what was removed and why — keep it removed.
+3. Copy the upstream `LICENSE` again if it changed, and update the commit and
+   notes in `SOURCE.md`.
+4. Check every `SKILL.md` still has `name` and `description` frontmatter, that
+   skill names stay unique across all packs, and that nothing points at the
+   upstream project's own install (paths into `~/.claude/skills/…`, its setup
+   or binaries). Then run the backend's tests: the loader test reads every
+   packaged pack.
+
+Nothing here fetches at build or test time; the packs are files in the repository.

package/starter-packs/engineering/KnowledgeBase/About us.md

@@ -0,0 +1,9 @@
+# About us
+
+What we build, for whom, and why, in a few sentences anyone on the team could repeat.
+
+- **What we build:** _one sentence a new engineer would understand_
+- **Who uses it:** _our customers or users, and what they rely on it for_
+- **The team:** _who works on what, and who to ask about each part_
+
+Ask your agent: _Draft this from our repository's README_

package/starter-packs/engineering/KnowledgeBase/Architecture.md

@@ -0,0 +1,9 @@
+# Architecture
+
+The main parts of the system and how they fit together, at the level a new engineer needs on day one.
+
+- **Components:** _the services, apps and libraries, one line each_
+- **How they talk:** _APIs, queues and events between them_
+- **Where data lives:** _databases and stores, and what each one holds_
+
+Ask your agent: _Draft this from our repository's README and code_

package/starter-packs/engineering/KnowledgeBase/Glossary.md

@@ -0,0 +1,9 @@
+# Glossary
+
+The words, acronyms and code names the engineering team uses, so a new person and their agent understand them.
+
+- **Terms and acronyms:** _each with one line on what it means here_
+- **Code names:** _projects, services and environments, and what they are_
+- **Easily confused:** _pairs of words that sound alike but mean different things here_
+
+Ask your agent: _Pull the terms from our repository, docs and recent pull requests_

package/starter-packs/engineering/KnowledgeBase/How we ship.md

@@ -0,0 +1,9 @@
+# How we ship
+
+How a change gets from an idea to production, so nobody has to ask twice.
+
+- **From idea to plan:** _where ideas are written down and who signs off on a plan_
+- **Review and merge:** _branching, who reviews, what has to pass before merging_
+- **Release:** _how and when we deploy, how we roll back, who is on call_
+
+Ask your agent: _Draft this from our CI configuration and contributing guide_

package/starter-packs/engineering/Plugins/engineering-starter/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garry Tan
+
+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/starter-packs/engineering/Plugins/engineering-starter/SOURCE.md

@@ -0,0 +1,20 @@
+# Source
+
+The skills in this plugin are adapted from gstack, Garry Tan's set of Claude Code skills.
+
+- Repository: https://github.com/garrytan/gstack
+- Commit: `db745675bdf9f575276db2dcd132d3c047218a12` (v1.91.33.0)
+- License: MIT, in `LICENSE` beside this file (Copyright (c) 2026 Garry Tan)
+
+Skills taken: `office-hours`, `plan-ceo-review`, `plan-eng-review` and `review`. Their method is gstack's — the forcing questions, the premise challenge and alternatives, the review modes and sections, the cognitive patterns, the error and rescue map, the test coverage diagram, the pre-landing checklist and the fix-first heuristic — and much of the wording is too. `office-hours/sections/phase-2a-startup-diagnostic.md` and `phase-2b-builder-brainstorm.md` are gstack's text with only the question-tool references removed, and `review/checklist.md` is gstack's checklist with the specialist-reviewer column and one suppression removed.
+
+Adapted for Hexis. gstack's skills are generated from templates and run inside a gstack install: every one starts with a preamble that calls gstack's own scripts (`~/.claude/skills/gstack/bin/…`: update checks, telemetry, session state, learnings, question preferences, review logs, a "brain" cache) and reads files gstack's `./setup` installs. None of that exists outside gstack, so each `SKILL.md` here was rewritten from its template as instructions that stand on their own:
+
+- dropped the preamble, telemetry, learnings capture and search, question tuning, the review log and readiness dashboard, the brain cache and write-back, plan-mode gates and the self-check against generated sections;
+- dropped the optional outside-voice review through the Codex CLI and the "Aside" browser research (web research now uses whatever search the agent has, with the same privacy rule), and office-hours' visual mockups, which need gstack's design binary;
+- dropped office-hours' builder profile and founder-resources closing, and review's Greptile triage, parallel specialist reviewers, exploratory QA, slop scan and adversarial pass, all of which run gstack tooling;
+- design docs, CEO plans and reviews are saved as pages in the Hexis knowledge base instead of `~/.gstack/projects/`, and earlier designs are found there;
+- the long generated `review-sections.md` of each plan review was condensed into its `SKILL.md`;
+- `allowed-tools` lists naming Claude Code's tools were removed, since Hexis matches that field against the tools in its own catalog.
+
+Not taken: `ship`, whose core steps (the review readiness gate, `gstack-version-bump`, `gstack-evidence`, `gstack-review-read`) are gstack scripts installed by its setup; and `retro`, whose metrics come from gstack's `gstack-retro-metrics` and `gstack-global-discover` programs.

package/starter-packs/engineering/Plugins/engineering-starter/access.md

@@ -0,0 +1,19 @@
+---
+# THIS BLOCK (the frontmatter) governs this access.md FILE only: who may
+# see it and who may change it. `read: everyone` here means every signed-in
+# person can see that the plugin exists. It admits nobody.
+read:
+  - everyone
+---
+# THIS BLOCK (the body) governs the PLUGIN FOLDER - its skills, tools and
+# manifest. A starter plugin is for the whole team, so everyone may use it
+# and admins change it. To narrow it, replace `everyone` under `read:` with a
+# role from roles.yaml (as `role/<Name>`, so a group of the same name can
+# never stand in for it), a group from groups.yaml, or a person as
+# `Name <email>`. Keep this block pure YAML; explanations go in `#` lines.
+read:
+  - everyone
+write:
+  - role/Admin
+owner:
+  - role/Admin

package/starter-packs/engineering/Plugins/engineering-starter/plugin.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "engineering-starter",
+  "displayName": "Engineering starter",
+  "description": "Think an idea through before building it, pressure-test a plan's scope, lock a plan's architecture and tests, and review a diff before it lands.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Garry Tan (gstack), adapted for Hexis by Bevel"
+  }
+}