bearings 0.3.4 → 0.5.0

package/templates/agents/skills/checklist/scripts/validate.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+const TOP_LEVEL_FIELDS = new Set(['title', 'summary', 'intro', 'callout', 'conventions', 'sections']);
+const SECTION_FIELDS = new Set(['number', 'title', 'kind', 'intro', 'items']);
+const ITEM_FIELDS = new Set([
+  'id',
+  'title',
+  'instruction',
+  'expectedResult',
+  'codeBlocks',
+  'links',
+  'optional',
+  'warning',
+  'failureGuidance',
+  'subItems',
+]);
+const SUB_ITEM_FIELDS = new Set([...ITEM_FIELDS].filter((field) => field !== 'subItems'));
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function rejectUnknownFields(value, allowed, path, errors) {
+  for (const field of Object.keys(value)) {
+    if (!allowed.has(field)) errors.push(`${path}.${field} is not allowed`);
+  }
+}
+
+function validateOptionalString(value, path, errors) {
+  if (value !== undefined && typeof value !== 'string') errors.push(`${path} must be a string`);
+}
+
+function validateCodeBlocks(value, path, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array`);
+    return;
+  }
+  value.forEach((block, index) => {
+    const blockPath = `${path}[${index}]`;
+    if (!isObject(block)) {
+      errors.push(`${blockPath} must be an object`);
+      return;
+    }
+    rejectUnknownFields(block, new Set(['language', 'content']), blockPath, errors);
+    if (!nonEmptyString(block.language)) errors.push(`${blockPath}.language must be a non-empty string`);
+    if (typeof block.content !== 'string') errors.push(`${blockPath}.content must be a string`);
+  });
+}
+
+function validateLinks(value, path, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array`);
+    return;
+  }
+  value.forEach((link, index) => {
+    const linkPath = `${path}[${index}]`;
+    if (!isObject(link)) {
+      errors.push(`${linkPath} must be an object`);
+      return;
+    }
+    rejectUnknownFields(link, new Set(['label', 'url']), linkPath, errors);
+    for (const field of ['label', 'url']) {
+      if (!nonEmptyString(link[field])) errors.push(`${linkPath}.${field} must be a non-empty string`);
+    }
+  });
+}
+
+function validateItem(item, path, ids, errors, subItem = false) {
+  if (!isObject(item)) {
+    errors.push(`${path} must be an object`);
+    return;
+  }
+  rejectUnknownFields(item, subItem ? SUB_ITEM_FIELDS : ITEM_FIELDS, path, errors);
+  for (const field of ['id', 'title']) {
+    if (!nonEmptyString(item[field])) errors.push(`${path}.${field} must be a non-empty string`);
+  }
+  if (nonEmptyString(item.id)) {
+    if (ids.has(item.id)) errors.push(`${path}.id duplicates "${item.id}"`);
+    ids.add(item.id);
+  }
+  for (const field of ['instruction', 'expectedResult', 'warning', 'failureGuidance']) {
+    validateOptionalString(item[field], `${path}.${field}`, errors);
+  }
+  if (item.optional !== undefined && typeof item.optional !== 'boolean') {
+    errors.push(`${path}.optional must be a boolean`);
+  }
+  validateCodeBlocks(item.codeBlocks, `${path}.codeBlocks`, errors);
+  validateLinks(item.links, `${path}.links`, errors);
+
+  if (subItem || item.subItems === undefined) return;
+  if (!Array.isArray(item.subItems)) {
+    errors.push(`${path}.subItems must be an array`);
+    return;
+  }
+  item.subItems.forEach((child, index) => validateItem(child, `${path}.subItems[${index}]`, ids, errors, true));
+}
+
+export function validateChecklist(checklist) {
+  const errors = [];
+  const ids = new Set();
+  if (!isObject(checklist)) return ['$ must be an object'];
+
+  rejectUnknownFields(checklist, TOP_LEVEL_FIELDS, '$', errors);
+  for (const field of ['title', 'summary']) {
+    if (!nonEmptyString(checklist[field])) errors.push(`$.${field} must be a non-empty string`);
+  }
+  for (const field of ['intro', 'callout', 'conventions']) {
+    validateOptionalString(checklist[field], `$.${field}`, errors);
+  }
+  if (!Array.isArray(checklist.sections) || checklist.sections.length === 0) {
+    errors.push('$.sections must be a non-empty array');
+    return errors;
+  }
+
+  checklist.sections.forEach((section, sectionIndex) => {
+    const sectionPath = `$.sections[${sectionIndex}]`;
+    if (!isObject(section)) {
+      errors.push(`${sectionPath} must be an object`);
+      return;
+    }
+    rejectUnknownFields(section, SECTION_FIELDS, sectionPath, errors);
+    for (const field of ['number', 'title']) {
+      if (!nonEmptyString(section[field])) errors.push(`${sectionPath}.${field} must be a non-empty string`);
+    }
+    if (!['checklist', 'info'].includes(section.kind)) {
+      errors.push(`${sectionPath}.kind must be "checklist" or "info"`);
+    }
+    validateOptionalString(section.intro, `${sectionPath}.intro`, errors);
+    if (!Array.isArray(section.items) || section.items.length === 0) {
+      errors.push(`${sectionPath}.items must be a non-empty array`);
+      return;
+    }
+    section.items.forEach((item, itemIndex) => validateItem(item, `${sectionPath}.items[${itemIndex}]`, ids, errors));
+  });
+
+  return errors;
+}
+
+export async function loadAndValidateChecklist(path) {
+  let checklist;
+  try {
+    checklist = JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    return { errors: [`Unable to read valid JSON: ${error.message}`] };
+  }
+  const errors = validateChecklist(checklist);
+  return errors.length === 0 ? { checklist, errors } : { errors };
+}
+
+async function main() {
+  const path = process.argv[2];
+  if (!path || process.argv.length !== 3) {
+    console.error('Usage: node validate.mjs <checklist.json>');
+    process.exitCode = 1;
+    return;
+  }
+  const { errors } = await loadAndValidateChecklist(path);
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`ERROR ${error}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log('OK');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();

package/templates/agents/skills/forge-a-skill/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: forge-a-skill
+description: Forge one codebase rule into a guardrail skill. Use only when the developer invokes /forge-a-skill by name.
+disable-model-invocation: true
+---
+
+# Forge a Skill
+
+Forge exactly one agent-owned guardrail skill. Do not continue unless the
+developer invoked `/forge-a-skill` by name.
+
+## Workflow
+
+### Step 1: Guard and input
+
+Confirm that the developer invoked `/forge-a-skill` by name. Take the rule from
+the invocation arguments. If there is no rule argument, ask one question for
+the rule. Stop if the skill was selected by the model instead of the developer.
+
+### Step 2: Apply the one-job test
+
+Ask yourself exactly one question: "Does this rule answer exactly one question
+an agent asks itself?" Split a rule joined by "and", or a rule whose correct
+tool depends on the request, into separate jobs. Forge only the first job and
+save each remaining job for the report as follow-up `/forge-a-skill` runs.
+
+### Step 3: Run the six-field interview
+
+Read the repository guidance and its routed knowledge maps first. Then inspect
+the relevant source, tests, configuration, and commands. Derive a candidate
+name from the rule using the naming contract in Step 4, then derive:
+
+- proposed anchors;
+- one to three exemplars cited as `path#symbol`;
+- a positive decision procedure;
+- a repository violation check command, or one concrete manual check;
+- current violations, including every finding's path and evidence; and
+- whether a guardrail of that name already exists.
+
+Do not treat a map statement as source evidence when a more direct file or
+symbol is available. Complete the scan before the interview only when it has
+one to three direct `path#symbol` exemplars. If none exists, stop and explain
+that the rule cannot be forged from current repository evidence. If an
+existing skill is a guardrail, this run is a **Re-forge**: use its current
+content as the interview defaults and update it in place after approval. If the
+existing canonical skill is not a guardrail, stop rather than replace it.
+
+Present all six fields in one message. This is one fixed round; do not spread
+the fields across multiple rounds. Present the one to three exemplars with the
+six fields. Propose Anchors, Decision procedure, and Violation check command
+from the scan. Ask the developer only for Question answered, Why, and
+Exceptions; let them correct any proposal.
+
+1. **Question answered**: the one question this rule answers.
+2. **Why**: the system scale and use case that make the rule suitable.
+3. **Anchors**: directories, libraries, layers, or verbs where the rule applies.
+4. **Decision procedure**: positive steps an agent follows.
+5. **Exceptions**: known cases where the rule does not apply.
+6. **Violation check command**: a repository command that detects violations,
+   or a concrete manual check when no command exists.
+
+### Step 4: Derive the skill contract
+
+- Choose a lowercase, hyphenated, plain trigger-word-led name. It must match the
+  directory `.agents/skills/<name>/`.
+- Write a description of at most 200 characters in exactly this form:
+  `<rule in one clause>. Use when planning, reviewing, or changing <anchors>.`
+- Use the interview answers to fill
+  `.agents/skills/forge-a-skill/templates/guardrail.md`. Keep its eight sections
+  in order and keep the body at most 60 lines. Include one to three direct
+  `path#symbol` exemplars. Use `None confirmed` only for an exception or
+  reference that the available evidence does not show.
+- Put the command and its success criterion in Verification. If there is no
+  command, put one concrete `Manual check:` line there.
+
+### Step 5: Show the plan and get approval
+
+Show the skill name, the description verbatim, anchors, exemplars, and
+verification command or manual check. List every current violation and require
+one choice for each finding before approval:
+
+- **Grandfather**: add it to Known exceptions with its path.
+- **Park**: delegate it to `defer-work`, which requires developer approval. This
+  skill does not park the work itself.
+
+Count unique project skills and personal skills on the developer's machine;
+do not count harness exposures or count an existing Re-forge twice. Sum their
+description character lengths, including the new or updated guardrail. Use the
+8,000-character budget and calculate
+`headroom = 8,000 - description characters`. Show the calculated plan line with
+all placeholders replaced:
+
+`Skill listing: <project-count> project skills + <personal-count> personal skills; <total> description characters; 8,000-character budget; <headroom> headroom.`
+
+If this rule is a consequential decision, offer to invoke
+`recording-decisions`; that skill owns any ADR. If the developer accepts,
+invoke `recording-decisions`, wait for its ADR path, and add that ADR path to
+the planned References before asking for approval. End with one explicit
+approval question. No guardrail file is written before the developer approves
+the complete plan and every violation has a disposition.
+
+### Step 6: Write the guardrail
+
+After approval, invoke `defer-work` for each parked finding. Then confirm that
+the name matches its directory, the description has the required form and is
+at most 200 characters, the fixed sections remain in order, Exemplars contains
+one to three `path#symbol` entries, and the body is at most 60 lines. Then
+create a new guardrail, or update it in place for a Re-forge:
+
+- Write `.agents/skills/<name>/SKILL.md` from the fixed guardrail template. Add
+  each grandfathered finding to Known exceptions with its path.
+- Write `.agents/skills/<name>/evals/evals.json` from
+  `.agents/skills/forge-a-skill/templates/probe-set.json`. Replace every
+  placeholder with concrete repository language. Keep five should-trigger
+  prompts across planning, design, review, editing, and refactoring phrasings,
+  and three should-not-trigger prompts outside the anchors. Each
+  `expected_output` must state whether the guardrail loads.
+
+Do not add the guardrail to `.agents/bearings.json`; forged skills are
+agent-owned project files. Stop rather than replace an existing canonical
+skill that is not a guardrail. Never edit source files or fix violations during
+a forge.
+
+### Step 7: Expose the guardrail
+
+If `.agents/bearings.json` does not exist, write only the canonical skill
+directory and state that no harness exposure was created. Otherwise, read
+`harnesses` and `exposure` from the Manifest:
+
+- For `symlink`, create `.<harness>/skills/<name>` as the relative symlink
+  `../../.agents/skills/<name>`.
+- For `copy`, recursively copy the canonical skill directory to
+  `.<harness>/skills/<name>`.
+
+Expose it to every configured harness. Do not change the Manifest or harness
+settings, and do not replace an unrelated exposure collision.
+
+### Step 8: Verify and report
+
+When a Manifest exists, run `npx bearings verify` and fix only guardrail or
+exposure errors from this run. Finish only when it reports zero failures.
+Report the canonical path, exposure paths, a `git diff` pointer for review, the
+fix list with every violation and its disposition, and all follow-up forges
+from Step 2. When there is no Manifest, clearly state that verification and
+exposure were not available.
+
+Recalculate the Step 5 skill-listing math from the files now on disk and repeat
+its exact `Skill listing:` line in the report.
+
+If headroom is 1,600 characters or less, advise the developer that they can
+raise `skillListingBudgetFraction`. Report only. Do not edit harness settings.
+Tell the developer to use `skill-creator` description tuning when it is
+installed. Otherwise, tell them to check all probes in a fresh session and
+confirm that should-trigger prompts load the guardrail and should-not-trigger
+prompts do not.
+
+## Wall
+
+This skill does not fix violations, record an ADR, park work, edit the Agent
+Seed, edit knowledge maps, edit harness settings, or approve anything on the
+developer's behalf. Delegate an approved ADR to `recording-decisions` and an
+approved deferral to `defer-work`.

package/templates/agents/skills/forge-a-skill/templates/guardrail.md

@@ -0,0 +1,45 @@
+---
+name: <skill-name>
+description: <description>
+metadata:
+  kind: guardrail
+  anchors:
+    - <anchor>
+---
+
+# <Guardrail title>
+
+## Why
+
+<System scale and use case that make this rule suitable.>
+
+## Applies when
+
+<Directories, libraries, layers, or verbs governed by this rule.>
+
+## Decision procedure
+
+1. <Positive step.>
+
+## Exemplars
+
+- `<path>#<symbol>` - <Established shape to follow. Include one to three exemplar lines.>
+
+## Known exceptions
+
+- <Known exception, or None confirmed.>
+- An agent may deviate only after asking the developer, then must add the approved exception here.
+
+## Does not govern
+
+<Nearest concern to which this rule must not be applied.>
+
+## Verification
+
+`<violation-check-command>`
+
+Completion criterion: <Observable successful result.>
+
+## References
+
+- <ADR or documentation path, or None confirmed.>

package/templates/agents/skills/forge-a-skill/templates/probe-set.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "<skill-name>",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Plan a change that touches <anchor> and explain the approach before editing.",
+      "expected_output": "The <skill-name> guardrail loads before the plan is written."
+    },
+    {
+      "id": 2,
+      "prompt": "Design a new <rule-subject> for <anchor>.",
+      "expected_output": "The <skill-name> guardrail loads while the design is prepared."
+    },
+    {
+      "id": 3,
+      "prompt": "Review the proposed work in <anchor> for compliance with repository patterns.",
+      "expected_output": "The <skill-name> guardrail loads for the review."
+    },
+    {
+      "id": 4,
+      "prompt": "Update <anchor> to support <rule-related-change>.",
+      "expected_output": "The <skill-name> guardrail loads before files are changed."
+    },
+    {
+      "id": 5,
+      "prompt": "Refactor the <rule-subject> implementation in <anchor>.",
+      "expected_output": "The <skill-name> guardrail loads for the edit."
+    },
+    {
+      "id": 6,
+      "prompt": "Plan an unrelated change in <outside-anchor>.",
+      "expected_output": "The <skill-name> guardrail does not load."
+    },
+    {
+      "id": 7,
+      "prompt": "Edit <outside-anchor> to update <unrelated-concern>.",
+      "expected_output": "The <skill-name> guardrail does not load."
+    },
+    {
+      "id": 8,
+      "prompt": "Explain <neighboring-concern> without changing repository files.",
+      "expected_output": "The <skill-name> guardrail does not load."
+    }
+  ]
+}

package/templates/agents/skills/manual-testplan/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: manual-testplan
+description: Design a small human-run browser or curl test plan from product scope. Use when the developer asks for a manual test plan, acceptance test plan, smoke test, or feature test checklist.
+---
+
+# Manual Test Plan
+
+Select the smallest useful set of human-executed cases, then delegate its
+checklist artifact to the `checklist` skill.
+
+## Workflow
+
+1. Establish the test basis. Read the requested issue, specification,
+   acceptance criteria, changed behavior, and relevant known defects. Identify
+   the primary actor, intended outcome, supported configuration, and explicit
+   product risks. Ask a small number of blocking questions when these facts do
+   not establish what success means.
+2. Map the basis to reachable public interfaces. Inspect repository maps,
+   runtime wiring, routes, UI flows, API contracts, authentication, feature
+   flags, test data, and supported setup, reset, and cleanup commands. Record
+   only browser and HTTP interfaces that a human can reach in the stated
+   environment.
+3. Select cases in execution order:
+   - Start with the shortest principal happy path that proves the actor reaches
+     the final intended outcome with ordinary valid data.
+   - Add uncovered acceptance criteria.
+   - Add only the highest-value alternatives and failures, selected from
+     likelihood and impact, materially different input partitions, boundaries,
+     business rules, state transitions, and relevant defect history.
+   - Remove duplicate coverage and cosmetic data variations. Keep each case an
+     independent, repeatable workflow with one main reason to fail.
+4. Define each case before delegation. Give it an outcome-focused title, the
+   criterion or risk it covers, its selection reason and priority,
+   configuration, known initial state, concrete non-secret data, ordered
+   actions and observable expectations, cleanup, and useful failure evidence.
+5. Invoke the `checklist` skill with the selected cases and require the output
+   at `checklists/tests/<slug>.json`. The `checklist` skill owns the JSON
+   contract, identifiers, checklist structure, validation, library build,
+   preview opening, and execution state.
+6. Review the resulting test content against the test basis. Every acceptance
+   criterion must be covered or named as an explicit gap, and every selected
+   risk must have a case whose oracle can detect that failure.
+
+## Browser Cases
+
+- State the tested build, browser, relevant viewport or device class, user
+  role, starting URL, and starting session state.
+- Write actions in user and domain language while naming controls clearly
+  enough to find. Put an observable expectation after each important
+  validation point and verify the final visible or persisted outcome.
+- Use supported fixtures, APIs, or seed commands for prerequisite data when
+  that keeps the browser workflow focused. Capture the current screen and exact
+  observed text first on failure.
+
+## Curl Cases
+
+- State the shell, base URL, authentication prerequisite, environment
+  variables, and data setup. Use secret placeholders such as `$TOKEN` through
+  the repository's established secret mechanism.
+- Give a directly runnable `curl` command with the evidenced method, quoted
+  URL, headers, and body. State the exact expected HTTP status, relevant
+  headers, body fields, and externally observable side effects.
+- Distinguish the HTTP result from curl's transfer exit status. State required
+  redirect and cookie behavior, preserve TLS verification unless the test
+  environment explicitly requires otherwise, and treat unexpected transport
+  failures as blocked environment failures.
+
+## Evidence Guardrail
+
+Requirements state intent; running code, configuration, contracts, tests, and
+developer confirmation establish reachable behavior. Ask for missing critical
+facts. Never invent commands, routes, URLs, credentials, selectors, status
+codes, response fields, messages, seed data, or cleanup behavior.
+
+## Completion
+
+Finish only when the test basis and reachable interfaces are explicit, the
+principal happy path proves the intended outcome, each additional case has a
+traceable risk or coverage reason, every oracle is concrete and observable,
+and the `checklist` skill completes one checklist under `checklists/tests/`.