@elvis1513/auto-coding-skill 5.0.5 → 5.1.0
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 +37 -1
- package/cli/assets/managed-install.json +8 -4
- package/cli/assets/skill/SKILL.md +23 -5
- package/cli/assets/skill/data/templates/PROJECT.md +25 -22
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +38 -5
- package/cli/assets/skill/references/parallel-development.md +61 -0
- package/cli/src/index.js +111 -4
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -6,7 +6,10 @@ small documentation layout. It is not a workflow engine.
|
|
|
6
6
|
The guidance preserves task authorization, scales verification to risk, and
|
|
7
7
|
defines completion by the user's requested outcome. It leaves model choice,
|
|
8
8
|
reasoning effort, and execution strategy to the user and runtime; it ships no
|
|
9
|
-
fixed agent profiles or
|
|
9
|
+
fixed agent profiles or Gate runtime. Repository changes use task-owned
|
|
10
|
+
`codex/*` branches and independent worktrees, with verified integration into
|
|
11
|
+
`dev`; read-only questions do not need a branch. Development stays parallel,
|
|
12
|
+
while integration resolves conflicts against current `dev` without force pushes.
|
|
10
13
|
|
|
11
14
|
## Install
|
|
12
15
|
|
|
@@ -46,6 +49,7 @@ review, test, or commit.
|
|
|
46
49
|
|
|
47
50
|
```bash
|
|
48
51
|
autocoding init
|
|
52
|
+
autocoding init --dry-run --json
|
|
49
53
|
autocoding sync --projects /path/project-a,/path/project-b
|
|
50
54
|
autocoding status --projects . --json
|
|
51
55
|
```
|
|
@@ -61,6 +65,26 @@ when both checks pass and no leftovers need review; otherwise status exits with
|
|
|
61
65
|
code 1. This is a local comparison, not an npm registry update check or an
|
|
62
66
|
engineering gate. Project-owned document contents are not inspected for drift.
|
|
63
67
|
|
|
68
|
+
`init`/`sync` preflight every requested project before refreshing any of them.
|
|
69
|
+
Modified or unowned files in the managed skill tree, `AGENTS.md`, or
|
|
70
|
+
`docs/ENVIRONMENT.md` block replacement; their contents are not printed.
|
|
71
|
+
`--dry-run --json` previews affected paths and conflicts without writing files.
|
|
72
|
+
Review the differences and migrate useful project facts into `PROJECT.md` or
|
|
73
|
+
topic documents first. If replacement is then intended, explicitly request it:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
autocoding init --replace-managed --backup-dir /private/external/skill-backups
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The backup directory must be outside all target projects, including through
|
|
80
|
+
symlinks. Each replacement creates a new private backup directory (0700), copies
|
|
81
|
+
the conflicting files with mode 0600, verifies their hashes, and records their
|
|
82
|
+
source paths. It does not overwrite an earlier backup. A dry-run does not create
|
|
83
|
+
backups. Review backups as potentially credential-bearing data; never commit them.
|
|
84
|
+
The override does not merge project instructions automatically or authorize
|
|
85
|
+
discarding them. Whole-batch preflight prevents known conflicts from producing a
|
|
86
|
+
partial upgrade; it is not a filesystem transaction for failures such as disk loss.
|
|
87
|
+
|
|
64
88
|
During upgrades, unchanged manifest-owned legacy files can be retired; the old
|
|
65
89
|
`docs/ENGINEERING.md` policy is archived first. Modified legacy files outside the
|
|
66
90
|
managed skill tree are preserved and reported across subsequent upgrades.
|
|
@@ -78,6 +102,11 @@ overwrite its own development instructions. Here, `status` reports source
|
|
|
78
102
|
discovery, packaged asset alignment, and legacy leftovers instead of expecting a
|
|
79
103
|
project install manifest.
|
|
80
104
|
|
|
105
|
+
Keep project constraints and validation entry points near the top of
|
|
106
|
+
`PROJECT.md`; read them before writing files or operating environments, including
|
|
107
|
+
when another skill suggests a default output path. Link to relevant existing
|
|
108
|
+
topic docs for historical detail. Shared managed files are not project overrides.
|
|
109
|
+
|
|
81
110
|
```bash
|
|
82
111
|
npm run sync-assets
|
|
83
112
|
npm run release:check
|
|
@@ -88,3 +117,10 @@ intended models: a read-only diagnosis, a focused fix, an already-authorized
|
|
|
88
117
|
delivery, and a blocked external job. Compare scope adherence, verification,
|
|
89
118
|
completion evidence, and unnecessary questions or repeated work. These are
|
|
90
119
|
evaluation scenarios, not required steps for every consuming project task.
|
|
120
|
+
|
|
121
|
+
Include regressions for artifact paths, managed-file ownership, preservation
|
|
122
|
+
during upgrades, concurrent worktrees with conflicting changes, and a completed
|
|
123
|
+
application delivery followed by an unrelated documentation build. The last case
|
|
124
|
+
must not add an unrequested CI wait or background monitor. For parallel work,
|
|
125
|
+
exercise a rejected stale push, conflict reconciliation, verification of both
|
|
126
|
+
changes, and non-force integration; do not merely test instruction wording.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schema_version": 2,
|
|
3
|
-
"skill_version": "5.0
|
|
3
|
+
"skill_version": "5.1.0",
|
|
4
4
|
"asset_files": [
|
|
5
5
|
{
|
|
6
6
|
"path": "SKILL.md",
|
|
7
|
-
"sha256": "
|
|
7
|
+
"sha256": "5d4f094f3de1287a44e989af19195ced866c98af58d56db7c0a018a11acf7e42"
|
|
8
8
|
},
|
|
9
9
|
{
|
|
10
10
|
"path": "data/templates/ENVIRONMENT.md",
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
14
|
"path": "data/templates/PROJECT.md",
|
|
15
|
-
"sha256": "
|
|
15
|
+
"sha256": "2a3de51f5bcb576a32d47d807ae17fd724e467da3edc03586dae332605ede2bd"
|
|
16
16
|
},
|
|
17
17
|
{
|
|
18
18
|
"path": "data/templates/architecture/.gitkeep",
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
},
|
|
21
21
|
{
|
|
22
22
|
"path": "data/templates/bridges/AGENTS.md",
|
|
23
|
-
"sha256": "
|
|
23
|
+
"sha256": "15d264c0f89ae571534444f5333785913a11cf75f27b8fccbb717b0c483595f1"
|
|
24
24
|
},
|
|
25
25
|
{
|
|
26
26
|
"path": "data/templates/deployment/.gitkeep",
|
|
@@ -37,6 +37,10 @@
|
|
|
37
37
|
{
|
|
38
38
|
"path": "data/templates/product/.gitkeep",
|
|
39
39
|
"sha256": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
|
|
40
|
+
},
|
|
41
|
+
{
|
|
42
|
+
"path": "references/parallel-development.md",
|
|
43
|
+
"sha256": "907f70aee2d58df1018daa26c3926201aa26c74b37d498aa13f8e6ebf8cae828"
|
|
40
44
|
}
|
|
41
45
|
]
|
|
42
46
|
}
|
|
@@ -5,8 +5,10 @@ description: Use when a project opts into auto-coding-skill or the user asks to
|
|
|
5
5
|
|
|
6
6
|
# Auto Coding Skill
|
|
7
7
|
|
|
8
|
-
Read `AGENTS.md
|
|
9
|
-
|
|
8
|
+
Read `AGENTS.md`. Before repository edits, artifact-producing tools, or environment
|
|
9
|
+
operations, read the applicable constraints and entry points in `docs/PROJECT.md`.
|
|
10
|
+
Start with its short current-context section and follow only relevant links;
|
|
11
|
+
do not routinely load its history or credential records in full.
|
|
10
12
|
|
|
11
13
|
- `docs/ENVIRONMENT.md` for shared access endpoints, ports, and local credential references.
|
|
12
14
|
- `docs/PROJECT.md` for project-specific runtime facts and configuration.
|
|
@@ -18,11 +20,27 @@ Use the project's guidance to choose an approach and enough verification for the
|
|
|
18
20
|
requested outcome. This Skill adds context, not a fixed task protocol or model
|
|
19
21
|
profile; it does not narrow existing authorization or redefine completion.
|
|
20
22
|
|
|
23
|
+
For repository changes, use a task-owned `codex/*` branch in an independent
|
|
24
|
+
worktree, then integrate the verified result into `dev`. Read
|
|
25
|
+
[parallel development](references/parallel-development.md) before creating or
|
|
26
|
+
integrating a task worktree. Read-only questions do not require a branch.
|
|
27
|
+
|
|
28
|
+
Project constraints govern tool output paths, including defaults from other
|
|
29
|
+
skills. Put temporary output in the project's approved location, normally
|
|
30
|
+
`.local/<task>/`; do not create root-level output directories by default.
|
|
31
|
+
|
|
21
32
|
Write documentation only when the user asks for it or when a durable fact,
|
|
22
33
|
contract, decision, test strategy, or operating procedure would otherwise be
|
|
23
34
|
lost. Choose the relevant existing folder; do not create routine task records,
|
|
24
35
|
review records, or duplicate summaries.
|
|
25
36
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
37
|
+
The installed skill, `AGENTS.md`, and `docs/ENVIRONMENT.md` are managed assets:
|
|
38
|
+
never append project-specific instructions or environment facts to them. Put
|
|
39
|
+
those in `docs/PROJECT.md` or its linked topic documents. Keep current constraints
|
|
40
|
+
and entry points prominent; maintain historical detail in the relevant existing
|
|
41
|
+
topic document rather than appending a diary to the project entry point.
|
|
42
|
+
|
|
43
|
+
`autocoding init` and `sync` preview changes with `--dry-run`. Modified or unowned
|
|
44
|
+
managed files block replacement until reviewed; migrate useful project content
|
|
45
|
+
first, then explicitly replace with a private external backup. Existing
|
|
46
|
+
`docs/PROJECT.md` and topic documents are never overwritten.
|
|
@@ -1,32 +1,35 @@
|
|
|
1
1
|
# Project Configuration
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
This file is project-owned. Skill installation creates it only when missing;
|
|
4
|
+
upgrades never overwrite it. Keep the current working context here and link to
|
|
5
|
+
maintained topic documents for detail, rather than accumulating task history.
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
or diagnosis. This project-owned document may contain project-approved plaintext
|
|
8
|
-
usernames and passwords for development and diagnosis. Keep each credential next
|
|
9
|
-
to its system, address, and purpose; do not echo it in chat or logs.
|
|
7
|
+
## Current working context
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
Record the facts needed before writing files or operating this project:
|
|
12
10
|
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
-
|
|
11
|
+
- Workspace constraints: approved directories, temporary output location, and
|
|
12
|
+
any concurrent work or external systems that must not be touched.
|
|
13
|
+
- Integration: `dev` is the integration target; each changing task uses its own
|
|
14
|
+
`codex/*` branch and independent worktree. Record any explicit project exception.
|
|
15
|
+
- Validation entry points: module working directories, focused checks, and the
|
|
16
|
+
acceptance boundaries relevant to delivery.
|
|
17
|
+
- Environment boundaries: deployment targets and actions requiring additional
|
|
18
|
+
authority. An endpoint or stored credential is not authorization to use it.
|
|
16
19
|
|
|
17
|
-
|
|
20
|
+
Replace this guidance with verified project facts; omit inapplicable fields and
|
|
21
|
+
identify genuinely unknown facts without inventing values.
|
|
18
22
|
|
|
19
|
-
|
|
20
|
-
- Credential records:
|
|
21
|
-
- Access constraints:
|
|
23
|
+
## Runtime and topic index
|
|
22
24
|
|
|
23
|
-
|
|
25
|
+
Keep current service endpoints and operating entry points here. Link to the
|
|
26
|
+
existing product, architecture, interface, design, and deployment documents only
|
|
27
|
+
when they help locate durable knowledge. Historical release and acceptance
|
|
28
|
+
evidence belongs in the relevant topic document, not in the current-context block.
|
|
24
29
|
|
|
25
|
-
|
|
26
|
-
- Relevant verification commands and acceptance criteria:
|
|
27
|
-
- Deployment topology:
|
|
28
|
-
- Logs and metrics:
|
|
30
|
+
## Access records
|
|
29
31
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
32
|
+
Project-approved credentials may be maintained here or at the project's approved
|
|
33
|
+
private location. Keep each record associated with its system and purpose.
|
|
34
|
+
Read only the required record; never print this whole file when it contains
|
|
35
|
+
credentials, and never echo secrets in chat, command arguments, or logs.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
<!-- auto-coding-skill:managed-agents:start version=5.0
|
|
1
|
+
<!-- auto-coding-skill:managed-agents:start version=5.1.0 -->
|
|
2
2
|
# General Engineering Guidance
|
|
3
3
|
|
|
4
4
|
## Authority and scope
|
|
@@ -20,10 +20,22 @@ An assessment or diagnosis alone does not authorize implementation or deployment
|
|
|
20
20
|
|
|
21
21
|
## Development approach
|
|
22
22
|
|
|
23
|
-
Choose an approach suited to the request's complexity and risk.
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
23
|
+
Choose an approach suited to the request's complexity and risk. Model choice and
|
|
24
|
+
reasoning effort belong to the user and runtime, not to a fixed profile in this
|
|
25
|
+
Skill. Design, review, and delegation should serve the task, not a fixed ceremony.
|
|
26
|
+
|
|
27
|
+
For every repository-changing request, use a task-owned `codex/*` branch in an
|
|
28
|
+
independent worktree based on current `dev`; do not edit in the shared `dev`
|
|
29
|
+
checkout or switch its branch while other conversations may use it. Reuse your
|
|
30
|
+
own active task branch for follow-ups. Read-only questions need no new branch.
|
|
31
|
+
Read `.agents/skills/auto-coding-skill/references/parallel-development.md` for
|
|
32
|
+
worktree isolation, conflict resolution, integration, and cleanup boundaries.
|
|
33
|
+
|
|
34
|
+
Complete and verify work on that branch, integrate the latest `dev`, resolve
|
|
35
|
+
conflicts preserving both tasks' valid changes, and recheck the affected behavior
|
|
36
|
+
before merging into `dev`. If `dev` advances, reconcile again; never force-push
|
|
37
|
+
or overwrite others' work to finish. Ask only when conflicting product intent
|
|
38
|
+
cannot be determined. Keep development parallel and integration serialized.
|
|
27
39
|
|
|
28
40
|
Verify the changed behavior and relevant failure paths with evidence proportionate
|
|
29
41
|
to the risk. Start with focused checks and broaden when impact or findings justify
|
|
@@ -36,8 +48,19 @@ and report the evidence for each. A launched command or background job is not a
|
|
|
36
48
|
successful result; follow required work to its terminal state. If that is not
|
|
37
49
|
possible, report the specific blocker or pending state without claiming completion.
|
|
38
50
|
|
|
51
|
+
Do not expand completion to unrelated CI, documentation builds, or extra reports.
|
|
52
|
+
Wait for CI/deployment only when required by the requested outcome or a concrete
|
|
53
|
+
failure relevant to it. Respect existing push hooks; do not trigger duplicate
|
|
54
|
+
builds or invent background monitoring to finish an otherwise completed task.
|
|
55
|
+
|
|
39
56
|
## Documentation
|
|
40
57
|
|
|
58
|
+
Before repository edits, tools that produce files, or environment operations,
|
|
59
|
+
read the applicable constraints and entry points in `docs/PROJECT.md`, then only
|
|
60
|
+
the topic sections needed for the task. Follow those output-path rules even when
|
|
61
|
+
another tool or skill recommends a different default. Temporary output belongs
|
|
62
|
+
in the approved location, normally `.local/<task>/`, not new root directories.
|
|
63
|
+
|
|
41
64
|
Read relevant project documentation before relying on project context:
|
|
42
65
|
|
|
43
66
|
- `docs/ENVIRONMENT.md`: shared GitLab, Nexus, Jenkins, and backend endpoint/port references. Managed and refreshed by the Skill.
|
|
@@ -48,12 +71,22 @@ Read relevant project documentation before relying on project context:
|
|
|
48
71
|
- `docs/interfaces/`: public API, event, protocol, or integration contracts.
|
|
49
72
|
- `docs/deployment/`: runbooks and durable operating procedures.
|
|
50
73
|
|
|
74
|
+
The installed Skill, `AGENTS.md`, and `docs/ENVIRONMENT.md` are shared managed
|
|
75
|
+
files. Do not add project-specific guidance, deployment facts, or credentials to
|
|
76
|
+
them; put those in `docs/PROJECT.md` or its linked topic documents. Do not edit
|
|
77
|
+
the install manifest to hide drift. Skill upgrades must review changed managed
|
|
78
|
+
files and preserve useful project content before explicit replacement.
|
|
79
|
+
|
|
51
80
|
Documentation is optional. Do not create a record for a routine edit, a transient
|
|
52
81
|
investigation, an ordinary review, or every commit. Record something only when the
|
|
53
82
|
user asks or when the information will remain useful after the immediate task.
|
|
54
83
|
Put it in the narrowest applicable folder and update an existing document instead
|
|
55
84
|
of creating parallel summaries.
|
|
56
85
|
|
|
86
|
+
Keep the project entry point focused on current constraints, runtime facts,
|
|
87
|
+
verification entry points, and links. Move useful historical evidence to existing
|
|
88
|
+
topic documents; do not turn `PROJECT.md` into a per-task or per-release diary.
|
|
89
|
+
|
|
57
90
|
## Environment and credentials
|
|
58
91
|
|
|
59
92
|
`docs/ENVIRONMENT.md` is shared managed context: it names endpoint ports and
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Parallel repository development
|
|
2
|
+
|
|
3
|
+
Use this reference for repository-changing work, not read-only diagnosis. The
|
|
4
|
+
user may explicitly change the branch policy; do not infer an exception merely
|
|
5
|
+
because an edit is small. This is isolation for concurrent conversations, not a
|
|
6
|
+
task-ledger, fixed-review, or model-selection protocol.
|
|
7
|
+
|
|
8
|
+
## Own a branch and a worktree
|
|
9
|
+
|
|
10
|
+
- Inspect the repository instructions, status, remotes, and existing worktrees.
|
|
11
|
+
Fetch the integration branch when available; start a unique `codex/<task>`
|
|
12
|
+
branch from current `dev`. Report an unavailable remote rather than pretending
|
|
13
|
+
an old base is current.
|
|
14
|
+
- Give the task an independent worktree. A different branch in the same directory
|
|
15
|
+
does not isolate files. Prefer the host's managed worktree tools when available;
|
|
16
|
+
otherwise use the project's approved worktree location. Keep temporary output
|
|
17
|
+
under that worktree's approved `.local/<task>/` location.
|
|
18
|
+
- Reuse the same task-owned branch/worktree for its follow-ups. Do not adopt,
|
|
19
|
+
reset, stash, switch, or remove another conversation's workspace. Existing
|
|
20
|
+
uncommitted work is not automatically part of the new request.
|
|
21
|
+
- Run edits, builds, formatters, and tests against the task worktree explicitly.
|
|
22
|
+
Do not apply a patch to the shared checkout accidentally. Shared output paths,
|
|
23
|
+
databases, devices, and deployments remain shared even with separate worktrees;
|
|
24
|
+
respect their own authorization and coordination boundaries.
|
|
25
|
+
|
|
26
|
+
## Integrate into dev
|
|
27
|
+
|
|
28
|
+
- Commit only the task's verified changes. Fetch current `dev` again before
|
|
29
|
+
integration. Merge it into the task branch, or rebase only task-owned history
|
|
30
|
+
when doing so will not rewrite another participant's work.
|
|
31
|
+
- Resolve both textual and semantic conflicts in the task worktree. Read the
|
|
32
|
+
surrounding code, contracts, and tests; preserve both tasks' valid behavior.
|
|
33
|
+
Do not use blanket `ours`/`theirs`, reset, or force pushes as conflict resolution.
|
|
34
|
+
Re-run the checks affected by the combination, not merely the old task checks.
|
|
35
|
+
- Resolve implementation conflicts directly when evidence is sufficient. If
|
|
36
|
+
product requirements genuinely contradict and the intended result is unknown,
|
|
37
|
+
preserve both versions and ask for that decision.
|
|
38
|
+
- Serialize the final integration attempt. Where available, use the repository's
|
|
39
|
+
existing merge queue or integration lock. A non-force Git push is the final
|
|
40
|
+
concurrency guard, not proof that a stale candidate is safe to combine.
|
|
41
|
+
- If no PR/merge queue is required and pushing is authorized, a verified task
|
|
42
|
+
branch containing the latest remote `dev` may be fast-forwarded to remote
|
|
43
|
+
`dev` from its own worktree (`git push origin HEAD:refs/heads/dev`). This avoids
|
|
44
|
+
editing or switching the shared checkout. If rejected because `dev` moved,
|
|
45
|
+
fetch, reconcile, verify the changed combination, and retry without force.
|
|
46
|
+
- Update a local `dev` checkout only when it is clean and not in use by another
|
|
47
|
+
task; otherwise leave it untouched and report that remote integration succeeded
|
|
48
|
+
while the shared checkout still needs a safe fast-forward. Never discard local
|
|
49
|
+
changes to synchronize it.
|
|
50
|
+
|
|
51
|
+
## Finish without losing work
|
|
52
|
+
|
|
53
|
+
Verify that the intended integration target contains the task commit. Distinguish
|
|
54
|
+
branch completion, dev integration, push, CI, deployment, and user/device
|
|
55
|
+
acceptance. Follow only the completion boundaries the user actually requested;
|
|
56
|
+
do not add unrelated CI waits or automatically start monitoring.
|
|
57
|
+
|
|
58
|
+
Remove/archive a task worktree or delete its branch only after its commits are
|
|
59
|
+
integrated, needed artifacts are preserved, it is clean, and no active task uses
|
|
60
|
+
it. Prefer recoverable worktree archival. Never bulk-delete `codex/*`: another
|
|
61
|
+
conversation may still be developing there.
|
package/cli/src/index.js
CHANGED
|
@@ -46,12 +46,15 @@ function copyTree(source, target) {
|
|
|
46
46
|
|
|
47
47
|
function parseArgs(argv) {
|
|
48
48
|
const [,, rawCommand, ...rest] = argv;
|
|
49
|
-
const args = { command: (!rawCommand || rawCommand === "-h" || rawCommand === "--help") ? "help" : rawCommand, dest: null, projects: [], json: false };
|
|
49
|
+
const args = { command: (!rawCommand || rawCommand === "-h" || rawCommand === "--help") ? "help" : rawCommand, dest: null, projects: [], json: false, dryRun: false, replaceManaged: false, backupDir: null };
|
|
50
50
|
for (let index = 0; index < rest.length; index += 1) {
|
|
51
51
|
const value = rest[index];
|
|
52
52
|
if (value === "--dest") args.dest = rest[++index] || fail("--dest requires a path");
|
|
53
53
|
else if (value === "--projects") args.projects.push(...(rest[++index] || fail("--projects requires paths")).split(",").filter(Boolean));
|
|
54
54
|
else if (value === "--json") args.json = true;
|
|
55
|
+
else if (value === "--dry-run") args.dryRun = true;
|
|
56
|
+
else if (value === "--replace-managed") args.replaceManaged = true;
|
|
57
|
+
else if (value === "--backup-dir") args.backupDir = rest[++index] || fail("--backup-dir requires a private external directory");
|
|
55
58
|
else if (value === "-h" || value === "--help") args.command = "help";
|
|
56
59
|
else if (value.startsWith("--")) fail(`unknown argument: ${value}`);
|
|
57
60
|
else args.projects.push(value);
|
|
@@ -59,6 +62,110 @@ function parseArgs(argv) {
|
|
|
59
62
|
return args;
|
|
60
63
|
}
|
|
61
64
|
|
|
65
|
+
function installSnapshot(root) {
|
|
66
|
+
const skill = managedTarget(root, ".agents/skills/auto-coding-skill");
|
|
67
|
+
const previous = readManifest(root);
|
|
68
|
+
const paths = new Set(["AGENTS.md", "docs/ENVIRONMENT.md", "docs/PROJECT.md", ".agents/managed-install.json"]);
|
|
69
|
+
if (skill && exists(skill)) {
|
|
70
|
+
if (!fs.statSync(skill).isDirectory()) fail("installed skill path is not a directory");
|
|
71
|
+
for (const file of listFiles(skill)) paths.add(`.agents/skills/auto-coding-skill/${file}`);
|
|
72
|
+
}
|
|
73
|
+
for (const entry of [...(Array.isArray(previous?.entries) ? previous.entries : []), ...(Array.isArray(previous?.legacy_entries) ? previous.legacy_entries : [])]) {
|
|
74
|
+
if (legacyManagedPath(entry?.path)) paths.add(entry.path);
|
|
75
|
+
}
|
|
76
|
+
return [...paths].sort().map(relative => {
|
|
77
|
+
const file = managedTarget(root, relative);
|
|
78
|
+
if (!file) fail(`unsafe install path: ${relative}`);
|
|
79
|
+
if (!exists(file)) return { path: relative, sha256: null };
|
|
80
|
+
if (!fs.statSync(file).isFile()) fail(`expected a regular file: ${relative}`);
|
|
81
|
+
return { path: relative, sha256: sha256(file) };
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function installationPlan(project) {
|
|
86
|
+
const root = fs.realpathSync(path.resolve(project));
|
|
87
|
+
if (sourceRepository(root)) fail("this is the skill source repository; use npm run sync-assets and npm run release:check, not init/sync");
|
|
88
|
+
for (const relative of [".agents/skills/auto-coding-skill", ".agents/managed-install.json", "AGENTS.md", ...bootstrapDocs.map(([, target]) => target)]) {
|
|
89
|
+
if (!managedTarget(root, relative)) fail(`unsafe install path (symlink or invalid path): ${relative}`);
|
|
90
|
+
}
|
|
91
|
+
const snapshot = installSnapshot(root);
|
|
92
|
+
const expected = new Map(expectedEntries().map(entry => [entry.path, entry.sha256]));
|
|
93
|
+
const previous = readManifest(root);
|
|
94
|
+
const recorded = new Map();
|
|
95
|
+
for (const entry of Array.isArray(previous?.entries) ? previous.entries : []) {
|
|
96
|
+
if (!safeRelativePath(entry?.path) || !/^[a-f0-9]{64}$/.test(entry?.sha256)) continue;
|
|
97
|
+
recorded.set(entry.path, recorded.has(entry.path) ? null : entry.sha256);
|
|
98
|
+
}
|
|
99
|
+
const conflicts = [];
|
|
100
|
+
for (const entry of snapshot) {
|
|
101
|
+
if (!entry.sha256 || !(entry.path.startsWith(".agents/skills/auto-coding-skill/") || ["AGENTS.md", "docs/ENVIRONMENT.md"].includes(entry.path))) continue;
|
|
102
|
+
if (entry.sha256 === expected.get(entry.path) || entry.sha256 === recorded.get(entry.path)) continue;
|
|
103
|
+
// The existing legacy migration copies this complete document into a new PROJECT.md.
|
|
104
|
+
if (entry.path === "docs/ENVIRONMENT.md" && !isManaged(previous, entry.path) && !exists(path.join(root, "docs/PROJECT.md"))) continue;
|
|
105
|
+
conflicts.push({ path: entry.path, sha256: entry.sha256, reason: recorded.has(entry.path) ? "modified managed file" : "unowned file would be replaced" });
|
|
106
|
+
}
|
|
107
|
+
const current = new Map(snapshot.map(entry => [entry.path, entry.sha256]));
|
|
108
|
+
const changes = [...expected].filter(([relative, digest]) => current.get(relative) !== digest)
|
|
109
|
+
.map(([relative]) => ({ path: relative, action: current.get(relative) ? "refresh" : "install" }));
|
|
110
|
+
for (const entry of snapshot) if (entry.sha256 && entry.path.startsWith(".agents/skills/auto-coding-skill/") && !expected.has(entry.path)) changes.push({ path: entry.path, action: "retire" });
|
|
111
|
+
return { project: root, conflicts, changes, snapshot };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
function assertUnchanged(plan) {
|
|
115
|
+
if (JSON.stringify(installSnapshot(plan.project)) !== JSON.stringify(plan.snapshot)) fail(`project changed during upgrade preparation; nothing further was refreshed: ${plan.project}`);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
function backupConflicts(plans, directory) {
|
|
119
|
+
const requested = path.resolve(directory);
|
|
120
|
+
// Resolve even a not-yet-created suffix, so a symlinked parent cannot point into a project.
|
|
121
|
+
let ancestor = requested;
|
|
122
|
+
const suffix = [];
|
|
123
|
+
while (!exists(ancestor)) { suffix.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
|
|
124
|
+
const resolved = path.join(fs.realpathSync(ancestor), ...suffix);
|
|
125
|
+
for (const plan of plans) {
|
|
126
|
+
const relative = path.relative(plan.project, resolved);
|
|
127
|
+
if (!relative || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))) fail("backup directory must be outside every target project");
|
|
128
|
+
}
|
|
129
|
+
fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
|
|
130
|
+
const backup = fs.mkdtempSync(path.join(resolved, "autocoding-managed-"));
|
|
131
|
+
fs.chmodSync(backup, 0o700);
|
|
132
|
+
const records = [];
|
|
133
|
+
for (const plan of plans) {
|
|
134
|
+
assertUnchanged(plan);
|
|
135
|
+
const key = `${path.basename(plan.project)}-${crypto.createHash("sha256").update(plan.project).digest("hex").slice(0, 12)}`;
|
|
136
|
+
for (const conflict of plan.conflicts) {
|
|
137
|
+
const target = path.join(backup, key, conflict.path);
|
|
138
|
+
fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
|
|
139
|
+
fs.writeFileSync(target, fs.readFileSync(path.join(plan.project, conflict.path)), { flag: "wx", mode: 0o600 });
|
|
140
|
+
if (sha256(target) !== conflict.sha256) fail("managed file changed while backing up; no replacement was started");
|
|
141
|
+
records.push({ project: plan.project, ...conflict, backup_path: path.relative(backup, target) });
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
fs.writeFileSync(path.join(backup, "backup.json"), `${JSON.stringify({ version: pkg.version, files: records }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
|
|
145
|
+
return backup;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function installProjects(projects, args) {
|
|
149
|
+
if (args.replaceManaged && !args.backupDir) fail("--replace-managed requires --backup-dir outside the target projects; review and migrate project facts first");
|
|
150
|
+
if (args.backupDir && !args.replaceManaged) fail("--backup-dir requires --replace-managed");
|
|
151
|
+
const plans = [...new Set(projects.map(project => fs.realpathSync(path.resolve(project))))].map(installationPlan);
|
|
152
|
+
const conflicts = plans.some(plan => plan.conflicts.length > 0);
|
|
153
|
+
const preview = { version: pkg.version, dry_run: args.dryRun, can_apply: !conflicts || args.replaceManaged, results: plans.map(({ snapshot, ...plan }) => plan) };
|
|
154
|
+
if (args.dryRun || (conflicts && !args.replaceManaged)) {
|
|
155
|
+
toJson(preview, args.json);
|
|
156
|
+
if (conflicts && !args.replaceManaged) {
|
|
157
|
+
console.error("[autocoding] No files changed. Review the listed files, migrate useful facts to PROJECT.md/topic docs, then use --replace-managed --backup-dir <private-external-directory> if replacement is intended. No file contents or credentials are printed.");
|
|
158
|
+
process.exitCode = 1;
|
|
159
|
+
}
|
|
160
|
+
return;
|
|
161
|
+
}
|
|
162
|
+
const backup = conflicts ? backupConflicts(plans, args.backupDir) : null;
|
|
163
|
+
// Preflight the whole batch before the first installation, not one project at a time.
|
|
164
|
+
for (const plan of plans) assertUnchanged(plan);
|
|
165
|
+
const results = plans.map(plan => { assertUnchanged(plan); return { ...init(plan.project), backup }; });
|
|
166
|
+
toJson(args.command === "init" ? results[0] : { version: pkg.version, results }, args.json);
|
|
167
|
+
}
|
|
168
|
+
|
|
62
169
|
function readManifest(project) {
|
|
63
170
|
const file = managedTarget(project, ".agents/managed-install.json");
|
|
64
171
|
if (!file || !exists(file)) return null;
|
|
@@ -301,15 +408,15 @@ function status(project) {
|
|
|
301
408
|
}
|
|
302
409
|
|
|
303
410
|
function help() {
|
|
304
|
-
console.log(`auto-coding-skill ${pkg.version}\n\nCommands:\n autocoding init [--dest PATH]\n autocoding sync [--projects PATH[,PATH...]]\n autocoding status [--projects PATH[,PATH...]] [--json]\n\nThese commands only install, preserve, and report documentation. They do not run
|
|
411
|
+
console.log(`auto-coding-skill ${pkg.version}\n\nCommands:\n autocoding init [--dest PATH] [--dry-run] [--json]\n autocoding sync [--projects PATH[,PATH...]] [--dry-run] [--json]\n autocoding status [--projects PATH[,PATH...]] [--json]\n\nChanged or unowned managed files block replacement. After reviewing and migrating project facts, use --replace-managed --backup-dir <private-external-directory> for a verified backup before explicit replacement. Dry-run never writes files.\n\nThese commands only install, preserve, and report documentation. They do not run project tests, Gates, worktrees, builds, or deployments. The installed guidance describes task-owned codex branches and worktrees; the installer does not create them.`);
|
|
305
412
|
}
|
|
306
413
|
|
|
307
414
|
const args = parseArgs(process.argv);
|
|
308
415
|
if (args.command === "help") help();
|
|
309
|
-
else if (args.command === "init")
|
|
416
|
+
else if (args.command === "init") installProjects([args.dest || process.cwd()], args);
|
|
310
417
|
else if (args.command === "sync") {
|
|
311
418
|
const projects = args.projects.length ? args.projects : [process.cwd()];
|
|
312
|
-
|
|
419
|
+
installProjects(projects, args);
|
|
313
420
|
} else if (args.command === "status") {
|
|
314
421
|
const projects = args.projects.length ? args.projects : [process.cwd()];
|
|
315
422
|
const results = projects.map(status);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@elvis1513/auto-coding-skill",
|
|
3
|
-
"version": "5.0
|
|
3
|
+
"version": "5.1.0",
|
|
4
4
|
"description": "Lightweight engineering guidance and a managed installer that preserves project-owned documentation.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"clean:cache": "find cli src -type d -name '__pycache__' -prune -exec rm -rf {} +",
|
|
18
18
|
"prepack": "npm run clean:cache",
|
|
19
19
|
"check:package": "npm run clean:cache && node cli/src/check-package.js",
|
|
20
|
-
"test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js",
|
|
20
|
+
"test": "node -c cli/src/index.js && node -c cli/src/sync-assets.js && node -c cli/tests/index.test.js && node cli/tests/index.test.js && node cli/tests/parallel.test.js",
|
|
21
21
|
"test:src": "node -e \"const fs=require('fs'); for (const file of ['src/auto-coding-skill/SKILL.md','src/auto-coding-skill/data/templates/ENVIRONMENT.md','src/auto-coding-skill/data/templates/PROJECT.md','src/auto-coding-skill/data/templates/architecture/.gitkeep','src/auto-coding-skill/data/templates/product/.gitkeep','src/auto-coding-skill/data/templates/bridges/AGENTS.md']) if (!fs.existsSync(file)) throw new Error('missing '+file); console.log('source-doc-assets-ok')\"",
|
|
22
22
|
"check:assets": "node cli/src/sync-assets.js --check",
|
|
23
23
|
"sync-assets": "node cli/src/sync-assets.js",
|