@1aboveio/skills 1.0.10 → 1.0.12

package/skills/engineering/engineering/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: engineering
+description: "Engineering conventions: feature-delivery priorities, focused verification and review, operational boundaries, and tracker routing. Standalone /engineering offers Global, Project, or Session setup and targeted resets for configured scopes; /engineering init keeps explicit project setup. Use when setting up AGENTS.md or CONTRIBUTING.md, saving or resetting engineering defaults, or before creating an engineering issue, spec, epic, ticket, or sub-issue on GitHub or Linear. Reads existing policy without writing during ordinary work. NOT the issue-to-PR workflow (resolve-issues), release execution (resolve-release), Git delivery (github-flow), or CI setup (github-actions)."
+release-version: 0.45.1
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Engineering
+
+Keep engineering work focused on the requested business outcome. Read the project's
+existing `AGENTS.md` and `CONTRIBUTING.md` and the relevant domain
+hazards or ADRs. Follow binding local requirements. Do not turn ordinary feature
+work into a setup, audit, framework, or gate project.
+
+## Find the task
+
+| Task | Action |
+| --- | --- |
+| Standalone `/engineering` or `engineering`, with no other task or scope | [Choose the scope](#choose-the-scope); ask before writing |
+| `/engineering init` or an explicit request to register project defaults | [Initialize](#initialize-project-guidance) |
+| Explicit request to save global defaults or use session-only defaults | Honor the named scope using [Choose the scope](#choose-the-scope); do not ask again |
+| Explicit request to reset one or more scopes | [Reset and clean up](references/scope-management.md#reset-and-clean-up) only the named scopes |
+| Ordinary implementation or review | Read applicable guidance; apply the defaults below without writing files |
+| Create an issue, spec, epic, or sub-issue | [Tracker routing](#tracker-routing); do not initialize as a side effect |
+| Existing guidance conflicts with a proposed default | Preserve it; ask for a decision only if the requested action needs one |
+| Choose additional setup capabilities | [Initialization scope](references/init-scope.md); route to the owning skill |
+
+## Choose the scope
+
+For every standalone invocation, inspect the known global instruction file, selected
+project guidance, and session choice without writing. Read
+[scope management](references/scope-management.md) for configuration detection,
+ownership records, and reset cleanup. Do not infer session setup from an automatic
+skill load or from inherited global or project rules.
+
+Ask one structured single-choice question when available. With no configured scope,
+ask "Where should the engineering rules apply?" with these options:
+
+| Choice | Meaning |
+| --- | --- |
+| Global | Save defaults in the current agent's global instructions for future projects and sessions |
+| Project | Save defaults in this project's `AGENTS.md` and `CONTRIBUTING.md` |
+| Session | Apply defaults for this session only; do not write files |
+
+When any scope is configured, ask "Which engineering scope should I set up or reset?"
+Keep all three scopes visible: offer `Reset Global`, `Reset Project`, or `Reset Session`
+for each configured scope, and `Set up Global`, `Set up Project`, or `Use for Session`
+for each unconfigured scope. Describe what is set, inherited, partial, or unresolved
+and name known target paths. Never label an unreadable or unknown scope as unset.
+A reset selection authorizes cleanup only for that scope. If the user explicitly
+requests several resets, process those scopes without asking them to choose one again.
+
+Wait for the answer before writing. If the user cancels or makes no selection,
+leave files unchanged.
+Automatic discovery, a handoff, quoted examples, and a task that merely mentions
+engineering do not show this question or authorize setup. A request to edit this
+skill is not an invocation to save its rules.
+
+- **Project:** The selection authorizes [project initialization](#initialize-project-guidance)
+  in the selected project, with its existing preservation and validation rules.
+  `/engineering init` remains a direct project setup request and skips this question.
+- **Session:** Read the delivery defaults, [engineering conventions](references/engineering-conventions.md),
+  [testing conventions](../test-quality/references/testing-conventions.md), and
+  [tracker routing](#tracker-routing), and apply them without saving guidance or
+  changing agent settings. Keep this choice across reload or compaction within
+  the current session; it expires in a new session. Existing binding requirements
+  and permissions still apply.
+- **Global:** The selection authorizes only the global guidance procedure below,
+  not project initialization. Do not pass a home or agent directory to `init.mjs`.
+
+### Save global defaults
+
+1. Resolve the current agent's supported user-level instruction file from the
+   active environment or its documented configuration. Show the exact path before
+   editing. If the destination is unknown or ambiguous, ask for it; do not guess
+   a path or write every agent's global files.
+2. Read existing global guidance and the feature-delivery, engineering, and testing
+   templates linked under project initialization. Use the scope-neutral rules from
+   those templates and tracker routing above; never copy the current project's
+   repository, Linear project, stack, commands, or delivery policy into global defaults.
+3. Validate the target before editing. Refuse unreadable or invalid files, dangling
+   links, and symlinks escaping the selected global instruction directory; preserve
+   valid links and edit their resolved target only once. Create only the selected
+   instruction file if missing. Keep the rules directly in that loaded file so future
+   sessions do not depend on a pointer to this skill's installation path.
+4. Add only missing defaults under `## Engineering defaults`, preserving existing
+   equivalent rules, hand edits, and unrelated instructions. Do not replace conflicting
+   policy without separate agreement. Repeating the same save is a no-op; a skill
+   update does not authorize refreshing saved rules. State that these are defaults
+   and that binding project requirements and action permissions still apply.
+   Record only this save's additions using the [ownership record](references/scope-management.md#record-ownership).
+5. Report the global scope, exact file created, updated, or already configured, and
+   any unresolved conflict or write failure. Do not change project files, install
+   dependencies, or perform delivery actions as part of saving defaults.
+
+## Delivery defaults
+
+Prioritize the requested outcome. Supporting code, tests, and infrastructure need
+a direct dependency, a binding requirement, or a demonstrated defect. Reuse existing
+patterns and sufficient proof. Preserve security, tenancy, financial correctness,
+data integrity, and cleanup. Do not invent recovery, compatibility, test layers,
+frameworks, or gates for speculative scenarios. Keep acceptance stable and stop when
+the outcome works and the agreed checks pass. Report unrelated debt without fixing it.
+
+These defaults do not waive project rules, authorize external actions, or require
+extra planning roles. Ordinary implementation choices stay with the implementer.
+
+## Initialize project guidance
+
+An explicit `/engineering init`, a Project selection above, or an explicit request
+to save project defaults authorizes the additions described here in the selected
+project. Automatic skill discovery, an issue-routing trigger, installation,
+updates, and quoted examples do not authorize writes. When defaults would help an
+unconfigured project, offer init once and continue; setup is not a feature prerequisite.
+
+1. Read existing project guidance and check for policy conflicts. The script preserves
+   existing sections; it does not interpret or replace the project's decisions.
+   Retain the before-state so the ownership record can distinguish new additions
+   from preserved sections and links.
+2. Set `SKILL_DIR` to this installed skill's directory. Preview:
+
+   ```sh
+   node "$SKILL_DIR/scripts/init.mjs" [--repo-root <project-root>] \
+     [--github-repo <owner/name>] [--linear-project "<name>"]...
+   ```
+
+3. For the explicitly authorized init, run the same command with `--write`. A preview
+   request alone stays read-only. No second approval is needed for the additions
+   already requested; a conflicting policy change needs separate agreement.
+   Record only newly added blocks, pointers, and created files using the
+   [ownership record](references/scope-management.md#record-ownership). A no-op init
+   does not adopt existing guidance or create an ownership record for it.
+4. Report created, updated, and preserved files and any unresolved project decisions.
+   Do not install dependencies, generate CI, create issues, push, or deploy as part of init.
+
+The default scope is the nearest Git root, or the current directory without a Git
+repository. `--repo-root` explicitly selects a different project. Do not walk parent
+projects or edit global agent files. A GitHub origin or explicit `--github-repo` supplies
+the known issue destination; without one, write neutral routing instructions and
+resolve the destination before any issue creation. Never infer a Linear project.
+
+| File or section | Init owns |
+| --- | --- |
+| `AGENTS.md` | Missing `Feature delivery` section and a pointer to `CONTRIBUTING.md` |
+| `CONTRIBUTING.md` | Missing `Engineering conventions`, `Testing conventions`, and `Issue tracking` sections |
+
+The templates are [feature delivery](references/feature-delivery.md),
+[engineering conventions](references/engineering-conventions.md),
+[testing conventions](../test-quality/references/testing-conventions.md), and
+[tracker conventions](references/tracker-conventions.md). Install `engineering` with
+its required sibling `test-quality`; init reads that skill's canonical template
+without invoking its writer. `test-quality` owns the testing rules and deliberate
+updates; init only adds a missing section. The [skill review](references/init-scope.md)
+explains what is included and what remains opt-in.
+
+Existing sections, including legacy `conventions:tracker` blocks written by
+`contributing`, are preserved byte-for-byte. Repeated init is not a refresh and
+leaves manual edits unchanged. No force/update mode is implied. If policy needs to
+change, agree the specific change rather than rerunning setup over it.
+
+Every target is checked before writing. Invalid targets, unreadable files, malformed
+owned markers, dangling links, and links outside the selected project refuse setup.
+Valid in-project symlinks are preserved. Keep distinct agent-instruction and
+contributor-guide files. Init does not read, create, or update `CLAUDE.md`.
+Report a write error honestly; do not claim setup completed when it did not.
+
+## Tracker routing
+
+Read the destination from project guidance first, then the GitHub resources linked
+from a source Linear project; ask if unresolved. An explicit user destination wins.
+
+| Work | Default tracker |
+| --- | --- |
+| Product goals, business requirements, consulting work, delivery summaries | Linear where used by the project |
+| Engineering specs, implementation epics, technical tasks, engineering bugs | GitHub |
+
+Before creating work:
+
+1. Classify the work, not the conversation it came from. Engineering implementation
+   stays in GitHub even when the request started in Linear.
+2. Resolve the actual repository. Do not guess among multiple repos or fall back to
+   Linear because the GitHub destination is missing.
+3. Search the destination for duplicates and reuse a match.
+4. Link the GitHub epic to its Linear source requirement once. Do not create
+   implementation children in Linear or mirror every ticket there.
+5. Report engineering delivery in Linear as a linked summary; the requester owns
+   product acceptance.
+
+The retained tracker-only helper supports explicit requests to persist or update
+that section:
+
+```sh
+node "$SKILL_DIR/scripts/persist-conventions.mjs" --repo-root <project-root> \
+  [--github-repo <owner/name>] [--linear-project "<name>"]... [--if-missing] [--write]
+```
+
+It previews without `--write`; `--if-missing` preserves an existing tracker block.
+Without that flag, an authorized tracker refresh replaces only its managed block.
+It retains the existing shared convention-writer behavior; use `init.mjs` for
+project setup with the all-target validation and preservation rules above. Ordinary
+issue routing never runs either writer automatically. The old `contributing` name
+is archived, not a second active policy owner.

package/skills/engineering/engineering/references/engineering-conventions.md

@@ -0,0 +1,32 @@
+## Engineering conventions
+
+### Deliver the requested outcome
+
+Build the smallest complete end-to-end change using existing patterns and tools.
+Supporting code, tests, and infrastructure need a direct dependency, a binding
+requirement, or a concrete defect. Do not invent fallback values, retries,
+compatibility modes, or abstractions for hypothetical future needs. Preserve
+necessary input validation and report unexpected failures through existing boundaries.
+
+### Verify proportionately
+
+Reuse tests and checks that already prove the changed behavior. Add focused proof
+for material risks at the lowest level that observes the real outcome. Mocks do
+not prove the persistence, authorization, or transaction behavior they replace.
+Do not duplicate proof across layers, pin source text instead of behavior, or
+start a whole-app audit for a local change. Run the project's required checks;
+report failed or unavailable checks honestly, without weakening them to get green.
+
+### Review and finish
+
+Block delivery for a concrete supported failure, an explicit unmet requirement,
+or missing agreed required proof, not speculative hardening or optional tests.
+Keep acceptance criteria stable; new scope needs agreement. Stop when the outcome
+works and the agreed checks pass. Report unrelated debt without fixing it.
+
+### Respect operational boundaries
+
+Preserve authentication, tenant isolation, financial correctness, data integrity,
+and cleanup. Follow this project's existing commit, PR, queue, and release policy.
+Do not invent a delivery flow, introduce new CI gates, or treat initialization as
+authorization to push, deploy, migrate shared data, change permissions, or release.

package/skills/engineering/engineering/references/feature-delivery.md

@@ -0,0 +1,8 @@
+## Feature delivery
+
+Prioritize the requested business outcome. Supporting engineering work must
+directly enable it, satisfy a binding requirement, or fix a concrete defect.
+Do not expand feature work into hardening, frameworks, coverage campaigns,
+or new gates without approval. Preserve required safety and correctness.
+Reuse sufficient proof and stop when the outcome and agreed checks pass.
+Report unrelated debt without implementing it.

package/skills/engineering/engineering/references/init-scope.md

@@ -0,0 +1,45 @@
+# What initialization includes
+
+Standalone `/engineering` first asks for Global, Project, or Session scope. Only a
+Project selection, `/engineering init`, or an explicit project save uses the project
+initializer described here. Global saving follows `SKILL.md`'s separate procedure;
+Session keeps the rules in conversation context without writing files.
+On later standalone calls, configured scopes offer a targeted reset with
+[owned-guidance cleanup](scope-management.md#reset-and-clean-up); setup does not
+grant permission to remove pre-existing rules.
+
+Project initialization creates durable guidance, not an orchestration or infrastructure setup.
+This review covers every active first-party skill in the Engineering package and
+the related delivery, CI, and merge-queue convention owners. Archived skills are
+not initialization sources; pinned external skills keep their upstream ownership.
+
+| Skill | Include in guidance | Keep as a separate action |
+| --- | --- | --- |
+| engineering (formerly contributing) | Feature priorities, guidance lookup, tracker routing | Tracker refresh or project-policy changes |
+| resolve-issues | Agreed outcome, bounded supporting work, explicit stopping point | Issue planning, workers, PRs, scheduling |
+| rush-issues | Same delivery principles as resolve-issues | Shortcut workflow invocation |
+| ensure-coverage | Smallest sufficient proof, stable acceptance, required checks preserved | Ledger adoption, broad audits, new gates |
+| test-quality | Canonical seven-principle `Testing conventions` section, added only when missing | Refreshing existing testing policy or suite cleanup |
+| e2e-test | Focus on affected journeys; distinguish real browser/backend proof | Harness, manifest, whole-app sweep |
+| better-review | Concrete blockers, optional improvements do not enlarge acceptance | Review passes, JSON records, re-review workflow |
+| golden-path | People choose release-blocking journeys | Path selection, contract, workflow and gate generation |
+| resolve-release | Respect existing release ownership and permissions | Flow selection, tags, deployment, promotion |
+| rush-release | Same release boundaries as resolve-release | Shortcut release invocation |
+| engineering-runtime | No user convention; support-only | Runtime installation or configuration |
+| harness-runtime | No user convention; support-only | Harness setup or configuration |
+| github-flow | Follow existing delivery policy; do not infer authorization | Declaring or changing Delivery and CI sections |
+| github-actions | Preserve existing required checks | Workflow generation, runner/caching/security policy |
+| mergify | Honor an existing queue policy | Queue installation, configuration, or enqueueing |
+| data-catalog | No general default; warehouse-specific rules need explicit setup | Data catalog conventions, catalog generation and CI |
+
+Do not invoke the separate actions as a side effect of `init`. In particular, do
+not call other skills' convention writers: they own their sections and may need
+additional decisions. Init reads `test-quality`'s canonical template directly;
+the testing owner and `conventions:testing` section identity remain unchanged.
+Existing project sections, including old testing and tracker blocks, stay unchanged.
+Delivery, CI, and Data Catalog conventions require separate explicit setup with
+their owning skills. Setup may point to these capabilities without requiring them.
+
+Stack-specific tools, commands, cloud projects, release branches, required gates,
+and golden paths are project facts, not defaults to manufacture. Read established
+guidance; ask for missing decisions only when a requested action needs them.

package/skills/engineering/engineering/references/scope-management.md

@@ -0,0 +1,85 @@
+# Scope management
+
+This procedure governs standalone setup and reset. It does not authorize cleanup
+while the skill is loaded for implementation, review, or tracker routing.
+
+## Detect configuration
+
+- Global uses only the current agent's supported user-level instruction file.
+  Project uses the selected Git root, or current directory without Git, and its
+  `AGENTS.md` and `CONTRIBUTING.md`. Apply the save procedure's target validation
+  before setup or reset. Do not scan unrelated projects or agent installations.
+- A valid ownership record, equivalent existing engineering rules, or an explicit
+  active session choice means the corresponding scope is configured. Distinguish
+  fully configured, partially configured, and existing rules not owned by this skill.
+  Rules inherited from another scope do not mean this scope is configured.
+- Inspect files afresh on every standalone call. Keep the session choice in context
+  across reload or compaction; a new session starts without that temporary choice.
+  A reset session choice remains off until the user explicitly enables it again.
+- Report unknown, unreadable, invalid, and conflicting guidance honestly. Offer to
+  resolve that scope rather than presenting a save or reset as safe. An unknown
+  global path does not prevent a known project or session action.
+
+## Record ownership
+
+After an authorized Global or Project save, keep a small JSON ownership record in
+an HTML comment in each changed guidance file:
+
+```markdown
+<!-- engineering:ownership
+{"version":1,"scope":"project","createdFile":false,"additions":[]}
+-->
+```
+
+Populate `additions` from the actual before/after diff, never from the presence of
+a familiar heading. Each entry has `namespace` (`conventions` or `engineering`),
+`id`, and `sha256` fields. These identify the `<!-- <namespace>:<id>:start -->`
+and matching `end` marker, and the SHA-256 of the bytes between them. Store marker
+identifiers, not literal comment strings, so the initializer does not count the
+receipt as duplicate markers. Include any new wrapper heading inside its recorded
+block. Record only newly inserted text. Use the
+existing `conventions:<id>:start/end` markers for new project sections. Wrap any
+new global defaults or new loading pointer in unique `engineering:<id>:start/end`
+comments before recording their hashes. Do not rewrap existing text or claim it as
+owned. Keep existing valid records and add only new entries; deduplicate entries.
+
+Set `createdFile` only when this save created that file. Preserve unrelated bytes
+and existing links. Do not create a sidecar, global settings entry, or project file
+for a session choice. A repeated save with no additions leaves files unchanged.
+If a record is malformed or ownership is uncertain, preserve the affected text and
+report the problem instead of inventing a receipt or claiming complete setup.
+
+## Reset and clean up
+
+A selected reset or an explicit scoped reset request authorizes removal of that
+scope's saved defaults, not a reinstall, refresh, or reset of every scope.
+
+1. Re-read and validate every target in the selected scope before editing. Explain
+   the planned removals and any preserved user rules. A read-only reset preview
+   stays read-only. Cancellation performs no cleanup.
+2. **Session:** Clear only the explicit temporary engineering choice. Do not edit
+   files or agent settings. Continue to honor inherited global and project rules
+   and binding requirements; session reset does not switch those off.
+3. **Global or Project:** Remove recorded additions only when their markers are
+   unique and balanced and their current content matches the recorded hash. Remove
+   their ownership entries as well. Retain edited blocks and their records, explain
+   the difference, and ask before removing user changes. Never delete an entire
+   section just because its heading matches a template.
+4. For older or unrecorded guidance, including legacy tracker blocks, ownership
+   cannot be inferred from markers alone. Identify the exact candidate text and
+   ask for agreement before deleting it. Do not adopt or erase rules written by
+   another skill. Safe, independently owned removals may proceed while an uncertain
+   removal remains unresolved; report the reset as partial.
+5. Remove owned loading pointers only if they are unchanged and no longer needed
+   by retained guidance. Keep a pointer that still loads user policy. Remove an
+   empty ownership record and any empty wrapper heading added by this save.
+   Delete a file only if `createdFile` proves this skill created it and nothing
+   except the original generated title and whitespace remains. Preserve pre-existing
+   files, symlinks, hand edits, and unrelated sections; never delete an instruction
+   directory or skill installation. Do not touch `CLAUDE.md` during project reset,
+   because project init does not own it.
+6. Report what was removed, retained, or blocked and which scopes still apply.
+   Resetting Project does not remove Global defaults, and resetting Global does
+   not erase project policy. Repeating a completed reset makes no file changes.
+   Reset does not disable ordinary read-only use of engineering defaults when a
+   later implementation or routing task loads this skill.

package/skills/engineering/engineering/scripts/init.mjs

@@ -0,0 +1,160 @@
+// Explicit project setup. Preview by default; preserve existing policy on every run.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const reference = name => fs.readFileSync(fileURLToPath(new URL(`../references/${name}.md`, import.meta.url)), 'utf8').trim()
+const usage = 'node init.mjs [--repo-root <dir>] [--github-repo <owner/name>] [--linear-project <name>]... [--write]'
+
+function parseArgs(argv) {
+  const options = { write: false, linearProjects: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--write') options.write = true
+    else if (arg === '--help') options.help = true
+    else if (['--repo-root', '--github-repo', '--linear-project'].includes(arg)) {
+      const value = argv[++i]
+      if (!value || value.startsWith('--') || /[\r\n]/.test(value)) throw new Error(`missing or invalid value for ${arg}`)
+      if (arg === '--repo-root') options.repoRoot = path.resolve(value)
+      else if (arg === '--github-repo') {
+        if (!/^[\w.-]+\/[\w.-]+$/.test(value)) throw new Error('invalid GitHub repository; use owner/name')
+        options.githubRepo = value
+      } else options.linearProjects.push(value)
+    } else throw new Error(`unknown argument ${arg}`)
+  }
+  return options
+}
+
+function gitOutput(root, args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+function githubRepo(root) {
+  const remote = gitOutput(root, ['remote', 'get-url', 'origin'])
+  return remote?.match(/^(?:git@github\.com:|https:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/)?.[1] ?? null
+}
+
+function inspectTarget(root, name) {
+  const file = path.join(root, name)
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false })
+  if (!stat) return { name, file, target: file, current: null }
+  const target = fs.realpathSync(file)
+  const relative = path.relative(root, target)
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`${name} resolves outside the selected project`)
+  }
+  if (!fs.statSync(target).isFile()) throw new Error(`${name} is not a regular file`)
+  return { name, file, target, current: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(target)) }
+}
+
+function append(current, body) {
+  const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n'
+  return `${current}${separator}${body.trim()}\n`
+}
+
+function preserveOrAdd(current, title, id, body) {
+  const start = `<!-- conventions:${id}:start -->`
+  const end = `<!-- conventions:${id}:end -->`
+  const starts = current.split(start).length - 1
+  const ends = current.split(end).length - 1
+  if (starts !== ends || starts > 1 || (starts && current.indexOf(start) > current.indexOf(end))) {
+    throw new Error(`malformed ${title} section markers; preserve and repair existing guidance first`)
+  }
+  if (starts || current.split(/\r?\n/).some(line => line.trim() === `## ${title}`)) return current
+  return append(current, `${start}\n${body}\n${end}`)
+}
+
+function linkFrom(from, to) {
+  return path.relative(path.dirname(from.target), to.file).split(path.sep).join('/')
+}
+
+function hasLoader(current, from, to) {
+  const links = /\[[^\]\r\n]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"'\r\n]*["'])?\s*\)/g
+  for (const match of current.matchAll(links)) {
+    const href = (match[1] ?? match[2]).split(/[?#]/)[0]
+    if (!href || /^[a-z][a-z\d+.-]*:|^\/\//i.test(href)) continue
+    let target
+    try {
+      target = path.resolve(path.dirname(from.target), decodeURIComponent(href))
+    } catch {
+      continue
+    }
+    if (fs.existsSync(target)) target = fs.realpathSync(target)
+    if (target === to.target) return true
+  }
+  return false
+}
+
+function trackerBody(repo, projects) {
+  if (repo) {
+    return reference('tracker-conventions')
+      .replaceAll('{{githubRepo}}', repo)
+      .replaceAll('{{linearProjects}}', projects.length ? ` (projects: ${projects.join(', ')})` : '')
+  }
+  return [
+    '## Issue tracking',
+    '',
+    'Follow existing project tracker decisions; an explicit user destination wins.',
+    'Use GitHub for engineering implementation and Linear for product requirements',
+    'and delivery summaries where the project uses those trackers. Before creating',
+    'an issue, resolve the actual repository from project guidance or the source',
+    'requirement; ask if it is unknown. Do not invent a repository or create trackers.',
+    'Search for duplicates and link implementation work back to its requirement.',
+    'Do not create implementation children in Linear.',
+    ...(projects.length ? ['', `Known Linear projects: ${projects.join(', ')}.`] : []),
+  ].join('\n')
+}
+
+function planInitialization(root, options) {
+  const [agents, contributing] = ['AGENTS.md', 'CONTRIBUTING.md']
+    .map(name => inspectTarget(root, name))
+  if (agents.target === contributing.target) {
+    throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
+  }
+
+  let agentText = preserveOrAdd(agents.current ?? '# Agent instructions\n', 'Feature delivery',
+    'feature-delivery', reference('feature-delivery'))
+  if (!hasLoader(agentText, agents, contributing)) {
+    agentText = append(agentText, `## Contributing\n\nFollow [CONTRIBUTING.md](${linkFrom(agents, contributing)}) for this project's engineering conventions and existing delivery requirements.`)
+  }
+
+  let contributingText = preserveOrAdd(contributing.current ?? '# Contributing\n', 'Engineering conventions',
+    'engineering', reference('engineering-conventions'))
+  const testing = fs.readFileSync(new URL('../../test-quality/references/testing-conventions.md', import.meta.url), 'utf8').trim()
+  contributingText = preserveOrAdd(contributingText, 'Testing conventions', 'testing', testing)
+  contributingText = preserveOrAdd(contributingText, 'Issue tracking', 'tracker',
+    trackerBody(options.githubRepo ?? githubRepo(root), options.linearProjects))
+
+  return [
+    { ...agents, next: agentText },
+    { ...contributing, next: contributingText },
+  ]
+}
+
+function main(argv) {
+  const options = parseArgs(argv)
+  if (options.help) {
+    console.log(usage)
+    return
+  }
+  const selected = options.repoRoot ?? gitOutput(process.cwd(), ['rev-parse', '--show-toplevel']) ?? process.cwd()
+  const root = fs.realpathSync(selected)
+  if (!fs.statSync(root).isDirectory()) throw new Error('project root is not a directory')
+  const plan = planInitialization(root, options)
+  console.log(`engineering init: ${options.write ? 'write' : 'preview only'} (${root})`)
+  for (const entry of plan) {
+    const action = entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update'
+    if (options.write && action !== 'unchanged') fs.writeFileSync(entry.target, entry.next)
+    console.log(`  ${entry.name}: ${!options.write && action !== 'unchanged' ? 'would ' : ''}${action}`)
+  }
+  console.log('Existing sections are preserved; initialization does not refresh project policy or authorize delivery actions.')
+}
+
+try {
+  main(process.argv.slice(2))
+} catch (error) {
+  console.error(`engineering init: ${error.message}`)
+  process.exitCode = 2
+}

package/skills/engineering/{contributing → engineering}/scripts/persist-conventions.mjs

@@ -77,7 +77,7 @@ function main(argv, { log = console.log } = {}) {
       return 0
     }
   }
-  const section = { id: ID, owner: 'contributing', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
+  const section = { id: ID, owner: 'engineering', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
   return runCli(rest, section, { log })
 }
 

package/skills/engineering/engineering-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: engineering-runtime
 description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.44.1
+release-version: 0.45.1
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Engineering Runtime