@1aboveio/engineering-skills 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -2
  3. package/skills/better-review/SKILL.md +37 -37
  4. package/skills/better-review/references/passes.md +35 -41
  5. package/skills/better-review/references/result.md +10 -9
  6. package/skills/e2e-test/SKILL.md +17 -17
  7. package/skills/e2e-test/references/authoring/playwright-config.md +11 -13
  8. package/skills/e2e-test/references/presentation-sweep.md +7 -7
  9. package/skills/e2e-test/references/reviewing.md +9 -11
  10. package/skills/e2e-test/references/route-manifest.md +1 -1
  11. package/skills/engineering/SKILL.md +124 -0
  12. package/skills/engineering/references/engineering-conventions.md +32 -0
  13. package/skills/engineering/references/feature-delivery.md +8 -0
  14. package/skills/engineering/references/init-scope.md +37 -0
  15. package/skills/engineering/scripts/init.mjs +160 -0
  16. package/skills/{contributing → engineering}/scripts/persist-conventions.mjs +1 -1
  17. package/skills/engineering-runtime/SKILL.md +1 -1
  18. package/skills/engineering-runtime/coherence/workflow.json +19 -19
  19. package/skills/engineering-runtime/scripts/workflow-policy.mjs +1 -1
  20. package/skills/ensure-coverage/SKILL.md +22 -109
  21. package/skills/ensure-coverage/references/breadth/coverage-ledger.md +7 -5
  22. package/skills/ensure-coverage/references/breadth/surface-baseline.md +4 -4
  23. package/skills/ensure-coverage/references/breadth/surface-discovery.md +3 -3
  24. package/skills/ensure-coverage/references/depth/characterization.md +4 -65
  25. package/skills/ensure-coverage/references/depth/grading.md +5 -7
  26. package/skills/ensure-coverage/references/depth/mock-policy.md +6 -12
  27. package/skills/ensure-coverage/references/enforcement/ci-contract.md +1 -1
  28. package/skills/ensure-coverage/references/presentation/axis.md +6 -6
  29. package/skills/ensure-coverage/references/process/audit-mode.md +7 -23
  30. package/skills/ensure-coverage/references/process/output-template.md +18 -133
  31. package/skills/ensure-coverage/references/process/test-strategy.md +7 -12
  32. package/skills/ensure-coverage/scripts/README.md +12 -4
  33. package/skills/golden-path/SKILL.md +1 -1
  34. package/skills/harness-runtime/SKILL.md +3 -1
  35. package/skills/harness-runtime/bin/workspaces.mjs +52 -0
  36. package/skills/harness-runtime/native-workspace.mjs +239 -0
  37. package/skills/harness-runtime/references/workspaces.md +78 -0
  38. package/skills/harness-runtime/workspace-lifecycle.mjs +2154 -0
  39. package/skills/resolve-issues/SKILL.md +40 -61
  40. package/skills/resolve-issues/references/ci.md +13 -3
  41. package/skills/resolve-issues/references/delivery-progress.md +4 -3
  42. package/skills/resolve-issues/references/done.md +11 -2
  43. package/skills/resolve-issues/references/expire.md +9 -2
  44. package/skills/resolve-issues/references/implementation.md +33 -17
  45. package/skills/resolve-issues/references/preflight.md +3 -1
  46. package/skills/resolve-issues/references/principles.md +52 -0
  47. package/skills/resolve-issues/references/review.md +25 -15
  48. package/skills/resolve-issues/references/task-plan.md +64 -27
  49. package/skills/resolve-issues/references/workspaces.md +164 -0
  50. package/skills/resolve-issues/scripts/cleanup-runs.mjs +185 -317
  51. package/skills/resolve-issues/scripts/next-actions.mjs +44 -7
  52. package/skills/resolve-issues/scripts/rehydrate.mjs +36 -2
  53. package/skills/resolve-issues/scripts/review-verdict.mjs +9 -8
  54. package/skills/resolve-issues/scripts/workspace-lifecycle.mjs +1 -0
  55. package/skills/resolve-release/SKILL.md +1 -1
  56. package/skills/rush-issues/SKILL.md +7 -5
  57. package/skills/rush-release/SKILL.md +1 -1
  58. package/skills/test-quality/SKILL.md +19 -4
  59. package/skills/test-quality/references/lint.md +1 -1
  60. package/skills/test-quality/references/principles.md +2 -2
  61. package/skills/test-quality/references/testing-conventions.md +1 -1
  62. package/skills/contributing/SKILL.md +0 -70
  63. /package/skills/{contributing → engineering}/LICENSE +0 -0
  64. /package/skills/{contributing → engineering}/references/tracker-conventions.md +0 -0
  65. /package/skills/{contributing → engineering}/release-check.mjs +0 -0
  66. /package/skills/{contributing → engineering}/scripts/persist-conventions-core.mjs +0 -0
@@ -4,11 +4,11 @@
4
4
 
5
5
  Checklist:
6
6
 
7
- - [ ] Route discovery and reachability analysis were run before coverage audit
8
- - [ ] Route manifest regenerated (projection) if routes added/removed; no drift vs the surface inventory
9
- - [ ] New routes have render-health proof (Tier 1, or a Tier 2/3 test calling `assertRenderHealthy`); no duplicate Tier 1 for a route already proven
10
- - [ ] Interactive routes have Tier 2 (success + error cases)
11
- - [ ] Browser-route changes ran the presentation sweep (a separate run); no `fail` results. **A `blocked` result depends on who is running this list.** Producing the work (fixtures yours to supply), `blocked` is a genuine gap — a route the harness cannot render is a route nobody proved renders, so it blocks. *Reviewing* a diff from a read-only sandbox, `blocked` usually means your environment lacks a `DATABASE_URL`, an auth session, or a resolvable param — an inability to verify, which is never evidence of absence. Report the route and the error and take `BLOCKED` for that route's obligation; do not convert it into a finding against the diff
7
+ - [ ] The affected business journey, relevant renders, and material errors have appropriate evidence from the existing suite or focused checks
8
+ - [ ] Reused journey assertions are credited only for what they actually check; functional success alone does not prove contrast or layout
9
+ - [ ] UX and layout claims have real-browser evidence; first-party interception is not real backend proof
10
+ - [ ] A whole-app sweep is scoped to an explicit audit, a shared-shell change with a real broad blast radius, or an existing binding repo requirement; discover and check reachability when conducting an audit
11
+ - [ ] Required checks ran, and actual failures or unverified obligations are reported with their cause. A reviewer's inability to run a check is not evidence that the diff lacks coverage
12
12
  - [ ] No `waitForTimeout()` -- use explicit waits
13
13
  - [ ] No CSS class assertions -- test user-visible behavior
14
14
  - [ ] **No test skipped or disabled.** The PR adds no `test.skip` / `xit` / `describe.skip`, no conditional skip unless CI still runs the test where the condition is false (a platform or optional-dependency skip), no disguised `if (!x) return` guard. A missing precondition is **seeded**; an un-sandboxable/flaky case goes to the **quarantine lane** (non-blocking, graded `Unverified`), never skipped. A `TODO`/issue link does **not** authorize a skip (policy: `ensure-coverage/references/process/test-strategy.md`)
@@ -17,10 +17,9 @@ Checklist:
17
17
  - [ ] Auth in shared fixtures, not duplicated
18
18
  - [ ] Bugfix PRs have regression test covering the exact failure
19
19
  - [ ] Tier 3 journeys use real APIs (no mocking internal endpoints)
20
- - [ ] Do-not-ship golden journeys (sign in → core action → pay) are tagged `@golden-path` so the golden-path check selects them; a new critical flow with no `@golden-path` tag / `golden-paths.json` entry is a gap
21
- - [ ] Specs tagged `@covers`/`@level` so the ledger resolves them
20
+ - [ ] Existing golden-path and ledger conventions are followed where required; no new gate is demanded automatically
22
21
 
23
- **Red flags (block PR):** route discovery/reachability not run before audit, route treated as valid only because a file exists, tests assert implementation details, fixed sleeps, new route without manifest entry, copy-pasted auth setup, happy-path-only Tier 2, no presentation sweep run for a browser-route change (a sweep you could not *run* is a `BLOCKED`, not a red flag — the distinction is whether the sweep is missing or your environment is), **any test skipped/disabled/guarded** instead of seeded-or-quarantined, an assertion that passes on a 404/not-found/empty page where a real render is expected, **an authorized lane whose only observed failure mode is a timeout** (it is failing closed before it renders, not asserting).
22
+ **Red flags:** treating a route as rendered only because a file exists, assertions that pass on a 404 or empty page, fixed sleeps, unsupported skips or guards, and an authorized lane that only times out instead of proving its subject rendered. Report material gaps and failures. Do not block solely for an absent manifest, sweep, or separate tier unless explicitly agreed or required by the repo.
24
23
 
25
24
  **Lead with the verdict, then follow-ups.** Put the verdict at the **top** of the review (and any coverage `notes.md`) — *is this surface covered / ship-ready, or do gaps remain?* — then what the tests prove and deliberately don't, and concrete follow-up action items (owner/level where known) for anything uncovered.
26
25
 
@@ -29,9 +28,8 @@ Checklist:
29
28
  ### E2E Coverage
30
29
 
31
30
  **Missing:**
32
- - Route `/new-page` added but not in the surface inventory / route manifest
33
- - No Tier 2 test for the date filter (need: valid range, invalid range, empty)
34
- - `/tasks` has no presentation-sweep result (render unproven)
31
+ - The affected date-filter journey has no evidence for its error state
32
+ - The claimed contrast improvement has no real-browser contrast evidence
35
33
 
36
34
  **Issues:**
37
35
  - `line 42`: Uses `waitForTimeout(3000)` -- replace with `waitForResponse`
@@ -1,6 +1,6 @@
1
1
  # Route Discovery and the Route Manifest
2
2
 
3
- > Read when: a route was added or removed, the manifest is stale, or an audit needs the route inventory before it can grade anything.
3
+ > Read when: an audit, a shared-shell change with a real broad blast radius, or a binding repo requirement needs route discovery or a current manifest. A routine route change does not itself require a whole-app inventory or regeneration.
4
4
 
5
5
  ## Discover first, never audit from memory
6
6
 
@@ -0,0 +1,124 @@
1
+ ---
2
+ name: engineering
3
+ description: "Project engineering conventions and explicit /engineering init: feature-delivery priorities, focused verification and review, operational boundaries, and tracker routing. Use when setting up AGENTS.md or CONTRIBUTING.md, saving 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)."
4
+ release-version: 0.45.0
5
+ ---
6
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
+ # Engineering
8
+
9
+ Keep engineering work focused on the requested business outcome. Read the project's
10
+ existing `AGENTS.md` and `CONTRIBUTING.md` and the relevant domain
11
+ hazards or ADRs. Follow binding local requirements. Do not turn ordinary feature
12
+ work into a setup, audit, framework, or gate project.
13
+
14
+ ## Find the task
15
+
16
+ | Task | Action |
17
+ | --- | --- |
18
+ | `/engineering init` or an explicit request to register project defaults | [Initialize](#initialize-project-guidance) |
19
+ | Ordinary implementation or review | Read applicable guidance; apply the defaults below without writing files |
20
+ | Create an issue, spec, epic, or sub-issue | [Tracker routing](#tracker-routing); do not initialize as a side effect |
21
+ | Existing guidance conflicts with a proposed default | Preserve it; ask for a decision only if the requested action needs one |
22
+ | Choose additional setup capabilities | [Initialization scope](references/init-scope.md); route to the owning skill |
23
+
24
+ ## Delivery defaults
25
+
26
+ Prioritize the requested outcome. Supporting code, tests, and infrastructure need
27
+ a direct dependency, a binding requirement, or a demonstrated defect. Reuse existing
28
+ patterns and sufficient proof. Preserve security, tenancy, financial correctness,
29
+ data integrity, and cleanup. Do not invent recovery, compatibility, test layers,
30
+ frameworks, or gates for speculative scenarios. Keep acceptance stable and stop when
31
+ the outcome works and the agreed checks pass. Report unrelated debt without fixing it.
32
+
33
+ These defaults do not waive project rules, authorize external actions, or require
34
+ extra planning roles. Ordinary implementation choices stay with the implementer.
35
+
36
+ ## Initialize project guidance
37
+
38
+ An explicit `/engineering init` authorizes the additions described here in the
39
+ selected project. Automatic skill discovery, an issue-routing trigger, installation,
40
+ updates, and quoted examples do not authorize writes. When defaults would help an
41
+ unconfigured project, offer init once and continue; setup is not a feature prerequisite.
42
+
43
+ 1. Read existing project guidance and check for policy conflicts. The script preserves
44
+ existing sections; it does not interpret or replace the project's decisions.
45
+ 2. Set `SKILL_DIR` to this installed skill's directory. Preview:
46
+
47
+ ```sh
48
+ node "$SKILL_DIR/scripts/init.mjs" [--repo-root <project-root>] \
49
+ [--github-repo <owner/name>] [--linear-project "<name>"]...
50
+ ```
51
+
52
+ 3. For the explicitly authorized init, run the same command with `--write`. A preview
53
+ request alone stays read-only. No second approval is needed for the additions
54
+ already requested; a conflicting policy change needs separate agreement.
55
+ 4. Report created, updated, and preserved files and any unresolved project decisions.
56
+ Do not install dependencies, generate CI, create issues, push, or deploy as part of init.
57
+
58
+ The default scope is the nearest Git root, or the current directory without a Git
59
+ repository. `--repo-root` explicitly selects a different project. Do not walk parent
60
+ projects or edit global agent files. A GitHub origin or explicit `--github-repo` supplies
61
+ the known issue destination; without one, write neutral routing instructions and
62
+ resolve the destination before any issue creation. Never infer a Linear project.
63
+
64
+ | File or section | Init owns |
65
+ | --- | --- |
66
+ | `AGENTS.md` | Missing `Feature delivery` section and a pointer to `CONTRIBUTING.md` |
67
+ | `CONTRIBUTING.md` | Missing `Engineering conventions`, `Testing conventions`, and `Issue tracking` sections |
68
+
69
+ The templates are [feature delivery](references/feature-delivery.md),
70
+ [engineering conventions](references/engineering-conventions.md),
71
+ [testing conventions](../test-quality/references/testing-conventions.md), and
72
+ [tracker conventions](references/tracker-conventions.md). Install `engineering` with
73
+ its required sibling `test-quality`; init reads that skill's canonical template
74
+ without invoking its writer. `test-quality` owns the testing rules and deliberate
75
+ updates; init only adds a missing section. The [skill review](references/init-scope.md)
76
+ explains what is included and what remains opt-in.
77
+
78
+ Existing sections, including legacy `conventions:tracker` blocks written by
79
+ `contributing`, are preserved byte-for-byte. Repeated init is not a refresh and
80
+ leaves manual edits unchanged. No force/update mode is implied. If policy needs to
81
+ change, agree the specific change rather than rerunning setup over it.
82
+
83
+ Every target is checked before writing. Invalid targets, unreadable files, malformed
84
+ owned markers, dangling links, and links outside the selected project refuse setup.
85
+ Valid in-project symlinks are preserved. Keep distinct agent-instruction and
86
+ contributor-guide files. Init does not read, create, or update `CLAUDE.md`.
87
+ Report a write error honestly; do not claim setup completed when it did not.
88
+
89
+ ## Tracker routing
90
+
91
+ Read the destination from project guidance first, then the GitHub resources linked
92
+ from a source Linear project; ask if unresolved. An explicit user destination wins.
93
+
94
+ | Work | Default tracker |
95
+ | --- | --- |
96
+ | Product goals, business requirements, consulting work, delivery summaries | Linear where used by the project |
97
+ | Engineering specs, implementation epics, technical tasks, engineering bugs | GitHub |
98
+
99
+ Before creating work:
100
+
101
+ 1. Classify the work, not the conversation it came from. Engineering implementation
102
+ stays in GitHub even when the request started in Linear.
103
+ 2. Resolve the actual repository. Do not guess among multiple repos or fall back to
104
+ Linear because the GitHub destination is missing.
105
+ 3. Search the destination for duplicates and reuse a match.
106
+ 4. Link the GitHub epic to its Linear source requirement once. Do not create
107
+ implementation children in Linear or mirror every ticket there.
108
+ 5. Report engineering delivery in Linear as a linked summary; the requester owns
109
+ product acceptance.
110
+
111
+ The retained tracker-only helper supports explicit requests to persist or update
112
+ that section:
113
+
114
+ ```sh
115
+ node "$SKILL_DIR/scripts/persist-conventions.mjs" --repo-root <project-root> \
116
+ [--github-repo <owner/name>] [--linear-project "<name>"]... [--if-missing] [--write]
117
+ ```
118
+
119
+ It previews without `--write`; `--if-missing` preserves an existing tracker block.
120
+ Without that flag, an authorized tracker refresh replaces only its managed block.
121
+ It retains the existing shared convention-writer behavior; use `init.mjs` for
122
+ project setup with the all-target validation and preservation rules above. Ordinary
123
+ issue routing never runs either writer automatically. The old `contributing` name
124
+ is archived, not a second active policy owner.
@@ -0,0 +1,32 @@
1
+ ## Engineering conventions
2
+
3
+ ### Deliver the requested outcome
4
+
5
+ Build the smallest complete end-to-end change using existing patterns and tools.
6
+ Supporting code, tests, and infrastructure need a direct dependency, a binding
7
+ requirement, or a concrete defect. Do not invent fallback values, retries,
8
+ compatibility modes, or abstractions for hypothetical future needs. Preserve
9
+ necessary input validation and report unexpected failures through existing boundaries.
10
+
11
+ ### Verify proportionately
12
+
13
+ Reuse tests and checks that already prove the changed behavior. Add focused proof
14
+ for material risks at the lowest level that observes the real outcome. Mocks do
15
+ not prove the persistence, authorization, or transaction behavior they replace.
16
+ Do not duplicate proof across layers, pin source text instead of behavior, or
17
+ start a whole-app audit for a local change. Run the project's required checks;
18
+ report failed or unavailable checks honestly, without weakening them to get green.
19
+
20
+ ### Review and finish
21
+
22
+ Block delivery for a concrete supported failure, an explicit unmet requirement,
23
+ or missing agreed required proof, not speculative hardening or optional tests.
24
+ Keep acceptance criteria stable; new scope needs agreement. Stop when the outcome
25
+ works and the agreed checks pass. Report unrelated debt without fixing it.
26
+
27
+ ### Respect operational boundaries
28
+
29
+ Preserve authentication, tenant isolation, financial correctness, data integrity,
30
+ and cleanup. Follow this project's existing commit, PR, queue, and release policy.
31
+ Do not invent a delivery flow, introduce new CI gates, or treat initialization as
32
+ authorization to push, deploy, migrate shared data, change permissions, or release.
@@ -0,0 +1,8 @@
1
+ ## Feature delivery
2
+
3
+ Prioritize the requested business outcome. Supporting engineering work must
4
+ directly enable it, satisfy a binding requirement, or fix a concrete defect.
5
+ Do not expand feature work into hardening, frameworks, coverage campaigns,
6
+ or new gates without approval. Preserve required safety and correctness.
7
+ Reuse sufficient proof and stop when the outcome and agreed checks pass.
8
+ Report unrelated debt without implementing it.
@@ -0,0 +1,37 @@
1
+ # What initialization includes
2
+
3
+ The default is durable project guidance, not an orchestration or infrastructure setup.
4
+ This review covers every active first-party skill in the Engineering package and
5
+ the related delivery, CI, and merge-queue convention owners. Archived skills are
6
+ not initialization sources; pinned external skills keep their upstream ownership.
7
+
8
+ | Skill | Include in guidance | Keep as a separate action |
9
+ | --- | --- | --- |
10
+ | engineering (formerly contributing) | Feature priorities, guidance lookup, tracker routing | Tracker refresh or project-policy changes |
11
+ | resolve-issues | Agreed outcome, bounded supporting work, explicit stopping point | Issue planning, workers, PRs, scheduling |
12
+ | rush-issues | Same delivery principles as resolve-issues | Shortcut workflow invocation |
13
+ | ensure-coverage | Smallest sufficient proof, stable acceptance, required checks preserved | Ledger adoption, broad audits, new gates |
14
+ | test-quality | Canonical seven-principle `Testing conventions` section, added only when missing | Refreshing existing testing policy or suite cleanup |
15
+ | e2e-test | Focus on affected journeys; distinguish real browser/backend proof | Harness, manifest, whole-app sweep |
16
+ | better-review | Concrete blockers, optional improvements do not enlarge acceptance | Review passes, JSON records, re-review workflow |
17
+ | golden-path | People choose release-blocking journeys | Path selection, contract, workflow and gate generation |
18
+ | resolve-release | Respect existing release ownership and permissions | Flow selection, tags, deployment, promotion |
19
+ | rush-release | Same release boundaries as resolve-release | Shortcut release invocation |
20
+ | engineering-runtime | No user convention; support-only | Runtime installation or configuration |
21
+ | harness-runtime | No user convention; support-only | Harness setup or configuration |
22
+ | github-flow | Follow existing delivery policy; do not infer authorization | Declaring or changing Delivery and CI sections |
23
+ | github-actions | Preserve existing required checks | Workflow generation, runner/caching/security policy |
24
+ | mergify | Honor an existing queue policy | Queue installation, configuration, or enqueueing |
25
+ | data-catalog | No general default; warehouse-specific rules need explicit setup | Data catalog conventions, catalog generation and CI |
26
+
27
+ Do not invoke the separate actions as a side effect of `init`. In particular, do
28
+ not call other skills' convention writers: they own their sections and may need
29
+ additional decisions. Init reads `test-quality`'s canonical template directly;
30
+ the testing owner and `conventions:testing` section identity remain unchanged.
31
+ Existing project sections, including old testing and tracker blocks, stay unchanged.
32
+ Delivery, CI, and Data Catalog conventions require separate explicit setup with
33
+ their owning skills. Setup may point to these capabilities without requiring them.
34
+
35
+ Stack-specific tools, commands, cloud projects, release branches, required gates,
36
+ and golden paths are project facts, not defaults to manufacture. Read established
37
+ guidance; ask for missing decisions only when a requested action needs them.
@@ -0,0 +1,160 @@
1
+ // Explicit project setup. Preview by default; preserve existing policy on every run.
2
+ import fs from 'node:fs'
3
+ import path from 'node:path'
4
+ import { spawnSync } from 'node:child_process'
5
+ import { fileURLToPath } from 'node:url'
6
+
7
+ const reference = name => fs.readFileSync(fileURLToPath(new URL(`../references/${name}.md`, import.meta.url)), 'utf8').trim()
8
+ const usage = 'node init.mjs [--repo-root <dir>] [--github-repo <owner/name>] [--linear-project <name>]... [--write]'
9
+
10
+ function parseArgs(argv) {
11
+ const options = { write: false, linearProjects: [] }
12
+ for (let i = 0; i < argv.length; i++) {
13
+ const arg = argv[i]
14
+ if (arg === '--write') options.write = true
15
+ else if (arg === '--help') options.help = true
16
+ else if (['--repo-root', '--github-repo', '--linear-project'].includes(arg)) {
17
+ const value = argv[++i]
18
+ if (!value || value.startsWith('--') || /[\r\n]/.test(value)) throw new Error(`missing or invalid value for ${arg}`)
19
+ if (arg === '--repo-root') options.repoRoot = path.resolve(value)
20
+ else if (arg === '--github-repo') {
21
+ if (!/^[\w.-]+\/[\w.-]+$/.test(value)) throw new Error('invalid GitHub repository; use owner/name')
22
+ options.githubRepo = value
23
+ } else options.linearProjects.push(value)
24
+ } else throw new Error(`unknown argument ${arg}`)
25
+ }
26
+ return options
27
+ }
28
+
29
+ function gitOutput(root, args) {
30
+ const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
31
+ return result.status === 0 ? result.stdout.trim() : null
32
+ }
33
+
34
+ function githubRepo(root) {
35
+ const remote = gitOutput(root, ['remote', 'get-url', 'origin'])
36
+ return remote?.match(/^(?:git@github\.com:|https:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/)?.[1] ?? null
37
+ }
38
+
39
+ function inspectTarget(root, name) {
40
+ const file = path.join(root, name)
41
+ const stat = fs.lstatSync(file, { throwIfNoEntry: false })
42
+ if (!stat) return { name, file, target: file, current: null }
43
+ const target = fs.realpathSync(file)
44
+ const relative = path.relative(root, target)
45
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
46
+ throw new Error(`${name} resolves outside the selected project`)
47
+ }
48
+ if (!fs.statSync(target).isFile()) throw new Error(`${name} is not a regular file`)
49
+ return { name, file, target, current: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(target)) }
50
+ }
51
+
52
+ function append(current, body) {
53
+ const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n'
54
+ return `${current}${separator}${body.trim()}\n`
55
+ }
56
+
57
+ function preserveOrAdd(current, title, id, body) {
58
+ const start = `<!-- conventions:${id}:start -->`
59
+ const end = `<!-- conventions:${id}:end -->`
60
+ const starts = current.split(start).length - 1
61
+ const ends = current.split(end).length - 1
62
+ if (starts !== ends || starts > 1 || (starts && current.indexOf(start) > current.indexOf(end))) {
63
+ throw new Error(`malformed ${title} section markers; preserve and repair existing guidance first`)
64
+ }
65
+ if (starts || current.split(/\r?\n/).some(line => line.trim() === `## ${title}`)) return current
66
+ return append(current, `${start}\n${body}\n${end}`)
67
+ }
68
+
69
+ function linkFrom(from, to) {
70
+ return path.relative(path.dirname(from.target), to.file).split(path.sep).join('/')
71
+ }
72
+
73
+ function hasLoader(current, from, to) {
74
+ const links = /\[[^\]\r\n]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"'\r\n]*["'])?\s*\)/g
75
+ for (const match of current.matchAll(links)) {
76
+ const href = (match[1] ?? match[2]).split(/[?#]/)[0]
77
+ if (!href || /^[a-z][a-z\d+.-]*:|^\/\//i.test(href)) continue
78
+ let target
79
+ try {
80
+ target = path.resolve(path.dirname(from.target), decodeURIComponent(href))
81
+ } catch {
82
+ continue
83
+ }
84
+ if (fs.existsSync(target)) target = fs.realpathSync(target)
85
+ if (target === to.target) return true
86
+ }
87
+ return false
88
+ }
89
+
90
+ function trackerBody(repo, projects) {
91
+ if (repo) {
92
+ return reference('tracker-conventions')
93
+ .replaceAll('{{githubRepo}}', repo)
94
+ .replaceAll('{{linearProjects}}', projects.length ? ` (projects: ${projects.join(', ')})` : '')
95
+ }
96
+ return [
97
+ '## Issue tracking',
98
+ '',
99
+ 'Follow existing project tracker decisions; an explicit user destination wins.',
100
+ 'Use GitHub for engineering implementation and Linear for product requirements',
101
+ 'and delivery summaries where the project uses those trackers. Before creating',
102
+ 'an issue, resolve the actual repository from project guidance or the source',
103
+ 'requirement; ask if it is unknown. Do not invent a repository or create trackers.',
104
+ 'Search for duplicates and link implementation work back to its requirement.',
105
+ 'Do not create implementation children in Linear.',
106
+ ...(projects.length ? ['', `Known Linear projects: ${projects.join(', ')}.`] : []),
107
+ ].join('\n')
108
+ }
109
+
110
+ function planInitialization(root, options) {
111
+ const [agents, contributing] = ['AGENTS.md', 'CONTRIBUTING.md']
112
+ .map(name => inspectTarget(root, name))
113
+ if (agents.target === contributing.target) {
114
+ throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
115
+ }
116
+
117
+ let agentText = preserveOrAdd(agents.current ?? '# Agent instructions\n', 'Feature delivery',
118
+ 'feature-delivery', reference('feature-delivery'))
119
+ if (!hasLoader(agentText, agents, contributing)) {
120
+ agentText = append(agentText, `## Contributing\n\nFollow [CONTRIBUTING.md](${linkFrom(agents, contributing)}) for this project's engineering conventions and existing delivery requirements.`)
121
+ }
122
+
123
+ let contributingText = preserveOrAdd(contributing.current ?? '# Contributing\n', 'Engineering conventions',
124
+ 'engineering', reference('engineering-conventions'))
125
+ const testing = fs.readFileSync(new URL('../../test-quality/references/testing-conventions.md', import.meta.url), 'utf8').trim()
126
+ contributingText = preserveOrAdd(contributingText, 'Testing conventions', 'testing', testing)
127
+ contributingText = preserveOrAdd(contributingText, 'Issue tracking', 'tracker',
128
+ trackerBody(options.githubRepo ?? githubRepo(root), options.linearProjects))
129
+
130
+ return [
131
+ { ...agents, next: agentText },
132
+ { ...contributing, next: contributingText },
133
+ ]
134
+ }
135
+
136
+ function main(argv) {
137
+ const options = parseArgs(argv)
138
+ if (options.help) {
139
+ console.log(usage)
140
+ return
141
+ }
142
+ const selected = options.repoRoot ?? gitOutput(process.cwd(), ['rev-parse', '--show-toplevel']) ?? process.cwd()
143
+ const root = fs.realpathSync(selected)
144
+ if (!fs.statSync(root).isDirectory()) throw new Error('project root is not a directory')
145
+ const plan = planInitialization(root, options)
146
+ console.log(`engineering init: ${options.write ? 'write' : 'preview only'} (${root})`)
147
+ for (const entry of plan) {
148
+ const action = entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update'
149
+ if (options.write && action !== 'unchanged') fs.writeFileSync(entry.target, entry.next)
150
+ console.log(` ${entry.name}: ${!options.write && action !== 'unchanged' ? 'would ' : ''}${action}`)
151
+ }
152
+ console.log('Existing sections are preserved; initialization does not refresh project policy or authorize delivery actions.')
153
+ }
154
+
155
+ try {
156
+ main(process.argv.slice(2))
157
+ } catch (error) {
158
+ console.error(`engineering init: ${error.message}`)
159
+ process.exitCode = 2
160
+ }
@@ -77,7 +77,7 @@ function main(argv, { log = console.log } = {}) {
77
77
  return 0
78
78
  }
79
79
  }
80
- const section = { id: ID, owner: 'contributing', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
80
+ const section = { id: ID, owner: 'engineering', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
81
81
  return runCli(rest, section, { log })
82
82
  }
83
83
 
@@ -3,7 +3,7 @@ name: engineering-runtime
3
3
  description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
4
4
  disable-model-invocation: true
5
5
  user-invocable: false
6
- release-version: 0.44.0
6
+ release-version: 0.45.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Engineering Runtime
@@ -11,7 +11,7 @@
11
11
  "golden-path",
12
12
  "test-quality",
13
13
  "better-review",
14
- "contributing",
14
+ "engineering",
15
15
  "engineering-runtime"
16
16
  ],
17
17
  "dependencies": [
@@ -369,7 +369,7 @@
369
369
  "repository": "1aboveio/ai",
370
370
  "revision": "main"
371
371
  },
372
- "contentDigest": "ae8ace5c97889e14e669829d72a92bd90d593ba1099c4bd690c98eca8b9c94e3",
372
+ "contentDigest": "8ab89f526fd30be9a81c8dc602d797e7aa8d2f09c63da0b56d8d214966e7e1fc",
373
373
  "digestExcludes": []
374
374
  },
375
375
  {
@@ -382,7 +382,7 @@
382
382
  "repository": "1aboveio/ai",
383
383
  "revision": "main"
384
384
  },
385
- "contentDigest": "ddf8e11e23f667cdc677c9d70edb6ed59da53b5a0b82af29f6be36eda35861c2",
385
+ "contentDigest": "386ab76e0a90f031da690ca27ee5066684d895290ae0c97faabf6aaad94cd495",
386
386
  "digestExcludes": []
387
387
  },
388
388
  {
@@ -395,7 +395,7 @@
395
395
  "repository": "1aboveio/ai",
396
396
  "revision": "main"
397
397
  },
398
- "contentDigest": "0e3c87b01b5c337a7628ae5ba5c78a3b208ab404b8d848e4d8299f221224726d",
398
+ "contentDigest": "0399fc78af9e7823ace55e04aa867b30b12c738f2a47e28395184512525861bf",
399
399
  "digestExcludes": []
400
400
  },
401
401
  {
@@ -408,7 +408,7 @@
408
408
  "repository": "1aboveio/ai",
409
409
  "revision": "main"
410
410
  },
411
- "contentDigest": "de98656af030369ea229112e90f441626863dcca5e21f2f358e26041d0624f3e",
411
+ "contentDigest": "2bc51a5c6ed89007075d51f174c7b76d0a743b61f0d299c2067487679c86dd3f",
412
412
  "digestExcludes": []
413
413
  },
414
414
  {
@@ -421,7 +421,7 @@
421
421
  "repository": "1aboveio/ai",
422
422
  "revision": "main"
423
423
  },
424
- "contentDigest": "c4f55e7aed013006d00fde40504db87c32c48ca8b04ef4aeacf9c7fe31995fed",
424
+ "contentDigest": "c3cd951d823c6ce4f2b9b229892e450ad285e27cda157c5eead0d8ddc3d550f5",
425
425
  "digestExcludes": []
426
426
  },
427
427
  {
@@ -434,7 +434,7 @@
434
434
  "repository": "1aboveio/ai",
435
435
  "revision": "main"
436
436
  },
437
- "contentDigest": "7ec336f6920ec1195fbe08b40234ac72f8213a3b94f575e2c463108b36884a25",
437
+ "contentDigest": "639a25b40d67942c5355abee9d791b02784bedc50fa1f5fb8b4d90125f0b95e7",
438
438
  "digestExcludes": []
439
439
  },
440
440
  {
@@ -447,7 +447,7 @@
447
447
  "repository": "1aboveio/ai",
448
448
  "revision": "main"
449
449
  },
450
- "contentDigest": "845c78252f5308aa71b8eaabc80718c25a772d016d5d74eb888737cd7ffbe664",
450
+ "contentDigest": "c595e281773af00b485dcb7d18e762f487b85761db42afa8287015581acdd8b5",
451
451
  "digestExcludes": []
452
452
  },
453
453
  {
@@ -460,7 +460,7 @@
460
460
  "repository": "1aboveio/ai",
461
461
  "revision": "main"
462
462
  },
463
- "contentDigest": "0c9e35d5014ebd7b4512aeb7705cd39977252ccaa639821fa87f8f463364b613",
463
+ "contentDigest": "ec21e8eb116ccf6b3c1e798f4039fc2fa05558e63cae157e0bcb75ea81627d68",
464
464
  "digestExcludes": []
465
465
  },
466
466
  {
@@ -473,7 +473,7 @@
473
473
  "repository": "1aboveio/ai",
474
474
  "revision": "main"
475
475
  },
476
- "contentDigest": "1c5c3dd92653706d7ca78926f10dbf266e4be4a807e6759ea6e8560b3be72f24",
476
+ "contentDigest": "d973f6bb977f4cba06e26afa42a54bbaa90d29001086c87a83d84f335df590d4",
477
477
  "digestExcludes": []
478
478
  },
479
479
  {
@@ -486,20 +486,20 @@
486
486
  "repository": "1aboveio/ai",
487
487
  "revision": "main"
488
488
  },
489
- "contentDigest": "d4f589fdb746755388a47eef8d34670a631584fac2bd32af1550da741434b4d6",
489
+ "contentDigest": "43d2be290e65e536f0b9ff21087cce81c337158948edbdf901c609d3e73b9b0b",
490
490
  "digestExcludes": []
491
491
  },
492
492
  {
493
- "installName": "contributing",
493
+ "installName": "engineering",
494
494
  "ownership": "owned",
495
- "sourcePath": "skills/engineering/contributing",
495
+ "sourcePath": "skills/engineering/engineering",
496
496
  "expectedSource": {
497
497
  "id": "first-party",
498
498
  "type": "first-party",
499
499
  "repository": "1aboveio/ai",
500
500
  "revision": "main"
501
501
  },
502
- "contentDigest": "d8b6513b1259b3b91f81c4ac9e9ebe66c2c3735534326ee793b99dc305dc3897",
502
+ "contentDigest": "73163c04711d6901162bd3cdb3a847db2845e8e51dbd53169ad13e7d2817f45c",
503
503
  "digestExcludes": []
504
504
  },
505
505
  {
@@ -512,13 +512,13 @@
512
512
  "repository": "1aboveio/ai",
513
513
  "revision": "main"
514
514
  },
515
- "contentDigest": "bf49dc85c84e81e6561b6682003709bb792f4309a295cddad2c5e97e5e85f5b1",
515
+ "contentDigest": "9086b011f69d48e264c00241c6c1864e04678f791f575625cff2e788a2b58163",
516
516
  "digestExcludes": [
517
517
  "coherence/workflow.json"
518
518
  ]
519
519
  }
520
520
  ],
521
- "releaseIdentity": "a7f5ec670bb7b0f8dcfb585c5de1d5cfd0bd55799d72e994034674c7c84f5c40",
521
+ "releaseIdentity": "986e36012356e16fd54d77f0844860cd5ed9c4cac6f18ef1d3d540a3697dcfdf",
522
522
  "lifecycleAuthority": "native-skills-cli",
523
523
  "repairRecipe": {
524
524
  "id": "engineering-workflow-dependency-first",
@@ -589,17 +589,17 @@
589
589
  "golden-path",
590
590
  "test-quality",
591
591
  "better-review",
592
- "contributing",
592
+ "engineering",
593
593
  "engineering-runtime"
594
594
  ],
595
595
  "commands": [
596
596
  {
597
597
  "transport": "https",
598
- "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
598
+ "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
599
599
  },
600
600
  {
601
601
  "transport": "ssh",
602
- "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
602
+ "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
603
603
  }
604
604
  ],
605
605
  "onFailure": {
@@ -16,7 +16,7 @@ export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
16
16
  'golden-path',
17
17
  'test-quality',
18
18
  'better-review',
19
- 'contributing',
19
+ 'engineering',
20
20
  'engineering-runtime',
21
21
  ]);
22
22