@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.
- package/README.md +1 -1
- package/package.json +2 -2
- package/skills/better-review/SKILL.md +37 -37
- package/skills/better-review/references/passes.md +35 -41
- package/skills/better-review/references/result.md +10 -9
- package/skills/e2e-test/SKILL.md +17 -17
- package/skills/e2e-test/references/authoring/playwright-config.md +11 -13
- package/skills/e2e-test/references/presentation-sweep.md +7 -7
- package/skills/e2e-test/references/reviewing.md +9 -11
- package/skills/e2e-test/references/route-manifest.md +1 -1
- package/skills/engineering/SKILL.md +124 -0
- package/skills/engineering/references/engineering-conventions.md +32 -0
- package/skills/engineering/references/feature-delivery.md +8 -0
- package/skills/engineering/references/init-scope.md +37 -0
- package/skills/engineering/scripts/init.mjs +160 -0
- package/skills/{contributing → engineering}/scripts/persist-conventions.mjs +1 -1
- package/skills/engineering-runtime/SKILL.md +1 -1
- package/skills/engineering-runtime/coherence/workflow.json +19 -19
- package/skills/engineering-runtime/scripts/workflow-policy.mjs +1 -1
- package/skills/ensure-coverage/SKILL.md +22 -109
- package/skills/ensure-coverage/references/breadth/coverage-ledger.md +7 -5
- package/skills/ensure-coverage/references/breadth/surface-baseline.md +4 -4
- package/skills/ensure-coverage/references/breadth/surface-discovery.md +3 -3
- package/skills/ensure-coverage/references/depth/characterization.md +4 -65
- package/skills/ensure-coverage/references/depth/grading.md +5 -7
- package/skills/ensure-coverage/references/depth/mock-policy.md +6 -12
- package/skills/ensure-coverage/references/enforcement/ci-contract.md +1 -1
- package/skills/ensure-coverage/references/presentation/axis.md +6 -6
- package/skills/ensure-coverage/references/process/audit-mode.md +7 -23
- package/skills/ensure-coverage/references/process/output-template.md +18 -133
- package/skills/ensure-coverage/references/process/test-strategy.md +7 -12
- package/skills/ensure-coverage/scripts/README.md +12 -4
- package/skills/golden-path/SKILL.md +1 -1
- package/skills/harness-runtime/SKILL.md +3 -1
- package/skills/harness-runtime/bin/workspaces.mjs +52 -0
- package/skills/harness-runtime/native-workspace.mjs +239 -0
- package/skills/harness-runtime/references/workspaces.md +78 -0
- package/skills/harness-runtime/workspace-lifecycle.mjs +2154 -0
- package/skills/resolve-issues/SKILL.md +40 -61
- package/skills/resolve-issues/references/ci.md +13 -3
- package/skills/resolve-issues/references/delivery-progress.md +4 -3
- package/skills/resolve-issues/references/done.md +11 -2
- package/skills/resolve-issues/references/expire.md +9 -2
- package/skills/resolve-issues/references/implementation.md +33 -17
- package/skills/resolve-issues/references/preflight.md +3 -1
- package/skills/resolve-issues/references/principles.md +52 -0
- package/skills/resolve-issues/references/review.md +25 -15
- package/skills/resolve-issues/references/task-plan.md +64 -27
- package/skills/resolve-issues/references/workspaces.md +164 -0
- package/skills/resolve-issues/scripts/cleanup-runs.mjs +185 -317
- package/skills/resolve-issues/scripts/next-actions.mjs +44 -7
- package/skills/resolve-issues/scripts/rehydrate.mjs +36 -2
- package/skills/resolve-issues/scripts/review-verdict.mjs +9 -8
- package/skills/resolve-issues/scripts/workspace-lifecycle.mjs +1 -0
- package/skills/resolve-release/SKILL.md +1 -1
- package/skills/rush-issues/SKILL.md +7 -5
- package/skills/rush-release/SKILL.md +1 -1
- package/skills/test-quality/SKILL.md +19 -4
- package/skills/test-quality/references/lint.md +1 -1
- package/skills/test-quality/references/principles.md +2 -2
- package/skills/test-quality/references/testing-conventions.md +1 -1
- package/skills/contributing/SKILL.md +0 -70
- /package/skills/{contributing → engineering}/LICENSE +0 -0
- /package/skills/{contributing → engineering}/references/tracker-conventions.md +0 -0
- /package/skills/{contributing → engineering}/release-check.mjs +0 -0
- /package/skills/{contributing → engineering}/scripts/persist-conventions-core.mjs +0 -0
|
@@ -4,11 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
Checklist:
|
|
6
6
|
|
|
7
|
-
- [ ]
|
|
8
|
-
- [ ]
|
|
9
|
-
- [ ]
|
|
10
|
-
- [ ]
|
|
11
|
-
- [ ]
|
|
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
|
-
- [ ]
|
|
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
|
|
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
|
-
-
|
|
33
|
-
-
|
|
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
|
|
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: '
|
|
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.
|
|
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
|
-
"
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
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": "
|
|
489
|
+
"contentDigest": "43d2be290e65e536f0b9ff21087cce81c337158948edbdf901c609d3e73b9b0b",
|
|
490
490
|
"digestExcludes": []
|
|
491
491
|
},
|
|
492
492
|
{
|
|
493
|
-
"installName": "
|
|
493
|
+
"installName": "engineering",
|
|
494
494
|
"ownership": "owned",
|
|
495
|
-
"sourcePath": "skills/engineering/
|
|
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": "
|
|
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": "
|
|
515
|
+
"contentDigest": "9086b011f69d48e264c00241c6c1864e04678f791f575625cff2e788a2b58163",
|
|
516
516
|
"digestExcludes": [
|
|
517
517
|
"coherence/workflow.json"
|
|
518
518
|
]
|
|
519
519
|
}
|
|
520
520
|
],
|
|
521
|
-
"releaseIdentity": "
|
|
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
|
-
"
|
|
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
|
|
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
|
|
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": {
|