@elvis1513/auto-coding-skill 5.0.4 → 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 +80 -5
- package/cli/assets/managed-install.json +8 -4
- package/cli/assets/skill/SKILL.md +27 -8
- package/cli/assets/skill/data/templates/PROJECT.md +25 -21
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +54 -9
- package/cli/assets/skill/references/parallel-development.md +61 -0
- package/cli/src/index.js +258 -35
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
# auto-coding-skill
|
|
2
2
|
|
|
3
|
-
`auto-coding-skill` 5.x provides
|
|
3
|
+
`auto-coding-skill` 5.x provides lightweight general engineering guidance plus a
|
|
4
4
|
small documentation layout. It is not a workflow engine.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
The guidance preserves task authorization, scales verification to risk, and
|
|
7
|
+
defines completion by the user's requested outcome. It leaves model choice,
|
|
8
|
+
reasoning effort, and execution strategy to the user and runtime; it ships no
|
|
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.
|
|
8
13
|
|
|
9
14
|
## Install
|
|
10
15
|
|
|
@@ -32,8 +37,10 @@ credential fields. `docs/PROJECT.md` is project-owned and never overwritten;
|
|
|
32
37
|
use it for project-specific configuration and project-approved credential
|
|
33
38
|
records.
|
|
34
39
|
|
|
35
|
-
|
|
36
|
-
`
|
|
40
|
+
The installed `.agents/skills/auto-coding-skill/` tree, `AGENTS.md`, and
|
|
41
|
+
`docs/ENVIRONMENT.md` are managed and refreshed by later `init` or `sync` runs.
|
|
42
|
+
Put custom guidance in project-owned documents, not managed files.
|
|
43
|
+
Project documents are created only when missing and are never
|
|
37
44
|
overwritten. Documentation is optional: record durable facts only when the user
|
|
38
45
|
asks or when they will help future work. Do not create a document for every task,
|
|
39
46
|
review, test, or commit.
|
|
@@ -42,6 +49,7 @@ review, test, or commit.
|
|
|
42
49
|
|
|
43
50
|
```bash
|
|
44
51
|
autocoding init
|
|
52
|
+
autocoding init --dry-run --json
|
|
45
53
|
autocoding sync --projects /path/project-a,/path/project-b
|
|
46
54
|
autocoding status --projects . --json
|
|
47
55
|
```
|
|
@@ -49,3 +57,70 @@ autocoding status --projects . --json
|
|
|
49
57
|
These commands only install, preserve, and report documentation. They never run
|
|
50
58
|
project tests, validation, Gates, reviews, builds, Jenkins jobs, deployment, or
|
|
51
59
|
other external-system operations.
|
|
60
|
+
|
|
61
|
+
`status` checks both install-time integrity (`integrity`) and alignment with the
|
|
62
|
+
running CLI's version and packaged assets (`current`). It also reports unexpected
|
|
63
|
+
installed skill files and recognizable legacy workflow files. `ok` is true only
|
|
64
|
+
when both checks pass and no leftovers need review; otherwise status exits with
|
|
65
|
+
code 1. This is a local comparison, not an npm registry update check or an
|
|
66
|
+
engineering gate. Project-owned document contents are not inspected for drift.
|
|
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
|
+
|
|
88
|
+
During upgrades, unchanged manifest-owned legacy files can be retired; the old
|
|
89
|
+
`docs/ENGINEERING.md` policy is archived first. Modified legacy files outside the
|
|
90
|
+
managed skill tree are preserved and reported across subsequent upgrades.
|
|
91
|
+
Unowned legacy candidates are reported, never automatically deleted. Review
|
|
92
|
+
their useful content before moving or removing them. Existing `docs/PROJECT.md`
|
|
93
|
+
is always preserved verbatim; a pre-managed environment document migrates intact
|
|
94
|
+
to `PROJECT.md` only when that project document is missing.
|
|
95
|
+
|
|
96
|
+
## Developing this skill
|
|
97
|
+
|
|
98
|
+
Edit `src/auto-coding-skill/`. The repository's discoverable skill at
|
|
99
|
+
`.agents/skills/auto-coding-skill` links directly to this source. Keep that symlink
|
|
100
|
+
intact; `autocoding init` and `sync` reject this source repository so they cannot
|
|
101
|
+
overwrite its own development instructions. Here, `status` reports source
|
|
102
|
+
discovery, packaged asset alignment, and legacy leftovers instead of expecting a
|
|
103
|
+
project install manifest.
|
|
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
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npm run sync-assets
|
|
112
|
+
npm run release:check
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Before changing shared instructions, try representative requests with the
|
|
116
|
+
intended models: a read-only diagnosis, a focused fix, an already-authorized
|
|
117
|
+
delivery, and a blocked external job. Compare scope adherence, verification,
|
|
118
|
+
completion evidence, and unnecessary questions or repeated work. These are
|
|
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
|
}
|
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: auto-coding-skill
|
|
3
|
-
description:
|
|
3
|
+
description: Use when a project opts into auto-coding-skill or the user asks to initialize, refresh, or inspect its project guidance and documentation. Provides context without imposing a fixed engineering workflow.
|
|
4
4
|
---
|
|
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.
|
|
@@ -14,14 +16,31 @@ current request:
|
|
|
14
16
|
- `docs/architecture/`, `docs/design/`, `docs/interfaces/`, and
|
|
15
17
|
`docs/deployment/` for existing topic-specific knowledge.
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
+
Use the project's guidance to choose an approach and enough verification for the
|
|
20
|
+
requested outcome. This Skill adds context, not a fixed task protocol or model
|
|
21
|
+
profile; it does not narrow existing authorization or redefine completion.
|
|
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.
|
|
19
31
|
|
|
20
32
|
Write documentation only when the user asks for it or when a durable fact,
|
|
21
33
|
contract, decision, test strategy, or operating procedure would otherwise be
|
|
22
34
|
lost. Choose the relevant existing folder; do not create routine task records,
|
|
23
35
|
review records, or duplicate summaries.
|
|
24
36
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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,31 +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
|
-
- Deployment topology:
|
|
27
|
-
- Logs and metrics:
|
|
30
|
+
## Access records
|
|
28
31
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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,9 +1,9 @@
|
|
|
1
|
-
<!-- auto-coding-skill:managed-agents:start version=5.
|
|
1
|
+
<!-- auto-coding-skill:managed-agents:start version=5.1.0 -->
|
|
2
2
|
# General Engineering Guidance
|
|
3
3
|
|
|
4
4
|
## Authority and scope
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
Follow the user's current goal and applicable instructions. Treat the current source,
|
|
7
7
|
tests, schemas, runtime configuration, and deployment configuration as the truth
|
|
8
8
|
for existing behavior. Documentation describes durable intent and operating
|
|
9
9
|
context; it must not override working code without an explicit decision.
|
|
@@ -13,19 +13,54 @@ Jenkins, production data, credentials, infrastructure, or another developer's
|
|
|
13
13
|
work. When a shared checkout contains unrelated changes, preserve them and avoid
|
|
14
14
|
reset, clean, overwrite, or bulk formatting operations.
|
|
15
15
|
|
|
16
|
+
Carry forward earlier authorization that still applies to this task, unless the
|
|
17
|
+
user changes or revokes it. Act on clear, reversible steps within that scope;
|
|
18
|
+
ask when missing information or new authority would materially change the result.
|
|
19
|
+
An assessment or diagnosis alone does not authorize implementation or deployment.
|
|
20
|
+
|
|
16
21
|
## Development approach
|
|
17
22
|
|
|
18
|
-
Choose
|
|
19
|
-
|
|
20
|
-
|
|
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.
|
|
39
|
+
|
|
40
|
+
Verify the changed behavior and relevant failure paths with evidence proportionate
|
|
41
|
+
to the risk. Start with focused checks and broaden when impact or findings justify
|
|
42
|
+
it. Honor required project checks; avoid repeating an unchanged check without a
|
|
43
|
+
reason. State what was verified and any remaining uncertainty.
|
|
21
44
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
45
|
+
Completion follows the requested outcome. Editing, committing, pushing, CI, and
|
|
46
|
+
deployment are distinct results: complete the authorized parts the goal requires
|
|
47
|
+
and report the evidence for each. A launched command or background job is not a
|
|
48
|
+
successful result; follow required work to its terminal state. If that is not
|
|
49
|
+
possible, report the specific blocker or pending state without claiming completion.
|
|
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.
|
|
26
55
|
|
|
27
56
|
## Documentation
|
|
28
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
|
+
|
|
29
64
|
Read relevant project documentation before relying on project context:
|
|
30
65
|
|
|
31
66
|
- `docs/ENVIRONMENT.md`: shared GitLab, Nexus, Jenkins, and backend endpoint/port references. Managed and refreshed by the Skill.
|
|
@@ -36,12 +71,22 @@ Read relevant project documentation before relying on project context:
|
|
|
36
71
|
- `docs/interfaces/`: public API, event, protocol, or integration contracts.
|
|
37
72
|
- `docs/deployment/`: runbooks and durable operating procedures.
|
|
38
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
|
+
|
|
39
80
|
Documentation is optional. Do not create a record for a routine edit, a transient
|
|
40
81
|
investigation, an ordinary review, or every commit. Record something only when the
|
|
41
82
|
user asks or when the information will remain useful after the immediate task.
|
|
42
83
|
Put it in the narrowest applicable folder and update an existing document instead
|
|
43
84
|
of creating parallel summaries.
|
|
44
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
|
+
|
|
45
90
|
## Environment and credentials
|
|
46
91
|
|
|
47
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,67 +62,192 @@ 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
|
-
const file =
|
|
64
|
-
if (!exists(file)) return null;
|
|
170
|
+
const file = managedTarget(project, ".agents/managed-install.json");
|
|
171
|
+
if (!file || !exists(file)) return null;
|
|
65
172
|
try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
|
|
66
173
|
}
|
|
67
174
|
|
|
175
|
+
function safeRelativePath(relative) {
|
|
176
|
+
return typeof relative === "string" && relative.length > 0
|
|
177
|
+
&& !relative.includes("\\") && !relative.includes("\0")
|
|
178
|
+
&& !relative.includes(":")
|
|
179
|
+
&& relative.split("/").every(part => part && part !== "." && part !== "..");
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// Managed paths must stay inside the project, including through parent symlinks.
|
|
183
|
+
function managedTarget(project, relative) {
|
|
184
|
+
if (!safeRelativePath(relative)) return null;
|
|
185
|
+
let target = project;
|
|
186
|
+
for (const part of relative.split("/")) {
|
|
187
|
+
target = path.join(target, part);
|
|
188
|
+
try { if (fs.lstatSync(target).isSymbolicLink()) return null; }
|
|
189
|
+
catch (error) { if (error.code !== "ENOENT") return null; }
|
|
190
|
+
}
|
|
191
|
+
return target;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
function sourceRepository(project) {
|
|
195
|
+
return exists(path.join(project, "src/auto-coding-skill/SKILL.md"))
|
|
196
|
+
&& exists(path.join(project, "cli/src/index.js"));
|
|
197
|
+
}
|
|
198
|
+
|
|
68
199
|
function legacyManagedPath(relative) {
|
|
69
|
-
return relative.startsWith(".agents/skills/auto-coding-skill/")
|
|
200
|
+
return safeRelativePath(relative) && (relative.startsWith(".agents/skills/auto-coding-skill/")
|
|
70
201
|
|| relative.startsWith(".agents/agents/")
|
|
71
202
|
|| relative === "docs/tools/autopipeline/ap.py"
|
|
72
|
-
|| relative === "docs/ENGINEERING.md";
|
|
203
|
+
|| relative === "docs/ENGINEERING.md");
|
|
73
204
|
}
|
|
74
205
|
|
|
75
206
|
function retireExactLegacyFiles(project) {
|
|
76
207
|
const previous = readManifest(project);
|
|
77
208
|
const retired = [];
|
|
78
|
-
|
|
79
|
-
|
|
209
|
+
const retained = [];
|
|
210
|
+
const entries = [...(Array.isArray(previous?.entries) ? previous.entries : []),
|
|
211
|
+
...(Array.isArray(previous?.legacy_entries) ? previous.legacy_entries : [])];
|
|
212
|
+
for (const entry of entries) {
|
|
80
213
|
if (!legacyManagedPath(entry?.path) || typeof entry.sha256 !== "string") continue;
|
|
81
|
-
const target =
|
|
214
|
+
const target = managedTarget(project, entry.path);
|
|
215
|
+
if (!target) continue;
|
|
82
216
|
if (exists(target) && fs.statSync(target).isFile() && sha256(target) === entry.sha256) {
|
|
83
217
|
if (entry.path === "docs/ENGINEERING.md") {
|
|
84
218
|
const version = String(previous.skill_version || "legacy").replace(/[^0-9A-Za-z._-]/g, "_");
|
|
85
|
-
const archive =
|
|
219
|
+
const archive = managedTarget(project, `.agents/archive/auto-coding-skill/${version}/docs/ENGINEERING.md`);
|
|
220
|
+
if (!archive) fail("unsafe legacy archive path; no policy file was removed");
|
|
86
221
|
copyFile(target, archive);
|
|
87
222
|
}
|
|
88
223
|
fs.rmSync(target);
|
|
89
224
|
retired.push(entry.path);
|
|
225
|
+
} else if (exists(target) && !entry.path.startsWith(".agents/skills/auto-coding-skill/")) {
|
|
226
|
+
retained.push(entry);
|
|
90
227
|
}
|
|
91
228
|
}
|
|
92
|
-
return retired;
|
|
229
|
+
return { retired, retained };
|
|
93
230
|
}
|
|
94
231
|
|
|
95
232
|
function isManaged(previous, relative) {
|
|
96
233
|
return Array.isArray(previous?.entries) && previous.entries.some(entry => entry?.path === relative && entry?.ownership === "managed");
|
|
97
234
|
}
|
|
98
235
|
|
|
99
|
-
function stripLegacyAccessConfiguration(text) {
|
|
100
|
-
return text.replace(/\n?## Migrated access configuration\s*\n```yaml\n[\s\S]*?\n```\s*/g, "\n").trim();
|
|
101
|
-
}
|
|
102
|
-
|
|
103
236
|
function migrateLegacyEnvironment(project) {
|
|
104
237
|
const previous = readManifest(project);
|
|
105
238
|
const environment = path.join(project, "docs", "ENVIRONMENT.md");
|
|
106
239
|
const projectConfig = path.join(project, "docs", "PROJECT.md");
|
|
107
|
-
if (exists(projectConfig))
|
|
108
|
-
const existing = fs.readFileSync(projectConfig, "utf8");
|
|
109
|
-
const cleaned = stripLegacyAccessConfiguration(existing);
|
|
110
|
-
if (cleaned !== existing.trim()) fs.writeFileSync(projectConfig, `${cleaned}\n`);
|
|
111
|
-
return false;
|
|
112
|
-
}
|
|
240
|
+
if (exists(projectConfig)) return false;
|
|
113
241
|
if (!exists(environment) || isManaged(previous, "docs/ENVIRONMENT.md")) return false;
|
|
114
|
-
const legacy =
|
|
115
|
-
if (!legacy) return false;
|
|
242
|
+
const legacy = fs.readFileSync(environment, "utf8");
|
|
243
|
+
if (!legacy.trim()) return false;
|
|
116
244
|
const template = fs.readFileSync(path.join(assetSkill, "data", "templates", "PROJECT.md"), "utf8").trimEnd();
|
|
117
245
|
mkdirFor(projectConfig);
|
|
118
246
|
fs.writeFileSync(projectConfig, `${template}\n\n## Migrated pre-5.0.1 environment context\n\n${legacy}\n`);
|
|
119
247
|
return true;
|
|
120
248
|
}
|
|
121
249
|
|
|
122
|
-
function buildManifest(project) {
|
|
250
|
+
function buildManifest(project, retained) {
|
|
123
251
|
const entries = [];
|
|
124
252
|
const installedSkill = path.join(project, ".agents", "skills", "auto-coding-skill");
|
|
125
253
|
for (const relative of listFiles(installedSkill)) {
|
|
@@ -134,6 +262,7 @@ function buildManifest(project) {
|
|
|
134
262
|
schema_version: 3,
|
|
135
263
|
skill_version: pkg.version,
|
|
136
264
|
entries,
|
|
265
|
+
legacy_entries: retained,
|
|
137
266
|
managed_documents: managedDocs.map(([, target]) => target),
|
|
138
267
|
project_documents: projectDocs.map(([, target]) => target),
|
|
139
268
|
note: "AGENTS.md and docs/ENVIRONMENT.md are refreshed by init/sync. Project documents are bootstrap-only and are never overwritten.",
|
|
@@ -143,7 +272,11 @@ function buildManifest(project) {
|
|
|
143
272
|
function init(project) {
|
|
144
273
|
const root = path.resolve(project);
|
|
145
274
|
if (!exists(root)) fail(`project directory does not exist: ${root}`);
|
|
146
|
-
|
|
275
|
+
if (sourceRepository(root)) fail("this is the skill source repository; use npm run sync-assets and npm run release:check, not init/sync");
|
|
276
|
+
for (const relative of [".agents/skills/auto-coding-skill", ".agents/managed-install.json", "AGENTS.md", ...bootstrapDocs.map(([, target]) => target)]) {
|
|
277
|
+
if (!managedTarget(root, relative)) fail(`unsafe install path (symlink or invalid path): ${relative}`);
|
|
278
|
+
}
|
|
279
|
+
const { retired, retained } = retireExactLegacyFiles(root);
|
|
147
280
|
const installedSkill = path.join(root, ".agents", "skills", "auto-coding-skill");
|
|
148
281
|
fs.rmSync(installedSkill, { recursive: true, force: true });
|
|
149
282
|
copyTree(assetSkill, installedSkill);
|
|
@@ -162,38 +295,128 @@ function init(project) {
|
|
|
162
295
|
created.push(targetRelative);
|
|
163
296
|
}
|
|
164
297
|
}
|
|
165
|
-
const manifest = buildManifest(root);
|
|
298
|
+
const manifest = buildManifest(root, retained);
|
|
166
299
|
const manifestPath = path.join(root, ".agents", "managed-install.json");
|
|
167
300
|
mkdirFor(manifestPath);
|
|
168
301
|
fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
|
169
|
-
return { project: root, version: pkg.version, created, retired, migrated_environment: migratedEnvironment, managed: manifest.entries.length };
|
|
302
|
+
return { project: root, version: pkg.version, created, retired, legacy_files: legacyFiles(root, manifest), migrated_environment: migratedEnvironment, managed: manifest.entries.length };
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
function expectedEntries() {
|
|
306
|
+
return [...listFiles(assetSkill).map(relative => ({
|
|
307
|
+
path: `.agents/skills/auto-coding-skill/${relative}`, sha256: sha256(path.join(assetSkill, relative)),
|
|
308
|
+
})), { path: "AGENTS.md", sha256: sha256(assetAgents) },
|
|
309
|
+
...managedDocs.map(([source, target]) => ({ path: target, sha256: sha256(path.join(assetSkill, "data/templates", source)) }))];
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
function legacyFiles(project, manifest) {
|
|
313
|
+
const candidates = new Set(["docs/tools/autopipeline/ap.py"]);
|
|
314
|
+
for (const entry of Array.isArray(manifest?.legacy_entries) ? manifest.legacy_entries : []) {
|
|
315
|
+
if (legacyManagedPath(entry?.path)) candidates.add(entry.path);
|
|
316
|
+
}
|
|
317
|
+
const agents = managedTarget(project, ".agents/agents");
|
|
318
|
+
const scan = ["docs/ENGINEERING.md"];
|
|
319
|
+
if (agents && exists(agents) && fs.statSync(agents).isDirectory()) {
|
|
320
|
+
scan.push(...fs.readdirSync(agents).filter(file => file.endsWith(".toml")).map(file => `.agents/agents/${file}`));
|
|
321
|
+
}
|
|
322
|
+
for (const relative of scan) {
|
|
323
|
+
const target = managedTarget(project, relative);
|
|
324
|
+
if (!target || !exists(target) || !fs.statSync(target).isFile()) continue;
|
|
325
|
+
const text = fs.readFileSync(target, "utf8");
|
|
326
|
+
if (/orchestration-v1\.schema\.json|ap\.py classify|docs\/tools\/autopipeline\//.test(text)
|
|
327
|
+
|| (relative === "docs/ENGINEERING.md" && text.includes("auto-coding-skill"))) candidates.add(relative);
|
|
328
|
+
}
|
|
329
|
+
return [...candidates].filter(relative => {
|
|
330
|
+
const target = managedTarget(project, relative);
|
|
331
|
+
return target && exists(target);
|
|
332
|
+
}).sort();
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
function sourceStatus(root) {
|
|
336
|
+
const errors = [];
|
|
337
|
+
const source = path.join(root, "src/auto-coding-skill");
|
|
338
|
+
const packaged = path.join(root, "cli/assets/skill");
|
|
339
|
+
const discovery = path.join(root, ".agents/skills/auto-coding-skill");
|
|
340
|
+
if (!exists(discovery) || fs.realpathSync(discovery) !== fs.realpathSync(source)) {
|
|
341
|
+
errors.push("source skill discovery must link to src/auto-coding-skill");
|
|
342
|
+
}
|
|
343
|
+
const sources = listFiles(source);
|
|
344
|
+
const assets = exists(packaged) ? listFiles(packaged) : [];
|
|
345
|
+
if (JSON.stringify(sources) !== JSON.stringify(assets)
|
|
346
|
+
|| sources.some(relative => !exists(path.join(packaged, relative)) || sha256(path.join(source, relative)) !== sha256(path.join(packaged, relative)))) {
|
|
347
|
+
errors.push("packaged skill differs from source; run npm run sync-assets");
|
|
348
|
+
}
|
|
349
|
+
let version = "";
|
|
350
|
+
try {
|
|
351
|
+
version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
|
|
352
|
+
const assetManifest = JSON.parse(fs.readFileSync(path.join(root, "cli/assets/managed-install.json"), "utf8"));
|
|
353
|
+
const expected = sources.map(relative => ({ path: relative, sha256: sha256(path.join(source, relative)) }));
|
|
354
|
+
if (assetManifest.schema_version !== 2 || assetManifest.skill_version !== version
|
|
355
|
+
|| JSON.stringify(assetManifest.asset_files) !== JSON.stringify(expected)) {
|
|
356
|
+
errors.push("packaged asset manifest differs from source; run npm run sync-assets");
|
|
357
|
+
}
|
|
358
|
+
} catch { errors.push("source package or asset manifest is missing or invalid"); }
|
|
359
|
+
const legacy = legacyFiles(root, null);
|
|
360
|
+
errors.push(...legacy.map(file => `legacy workflow file requires review: ${file}`));
|
|
361
|
+
return { project: root, mode: "source", version, ok: errors.length === 0, errors, legacy_files: legacy };
|
|
170
362
|
}
|
|
171
363
|
|
|
172
364
|
function status(project) {
|
|
173
365
|
const root = path.resolve(project);
|
|
366
|
+
if (sourceRepository(root)) return sourceStatus(root);
|
|
174
367
|
const manifest = readManifest(root);
|
|
175
|
-
const
|
|
176
|
-
|
|
368
|
+
const integrityErrors = [];
|
|
369
|
+
const currentErrors = [];
|
|
370
|
+
if (!manifest) integrityErrors.push("managed install manifest is missing or invalid");
|
|
177
371
|
const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
|
|
372
|
+
if (!entries.length) integrityErrors.push("managed install manifest has no entries");
|
|
373
|
+
const seen = new Set();
|
|
374
|
+
for (const entry of entries) {
|
|
375
|
+
const target = managedTarget(root, entry?.path);
|
|
376
|
+
if (!target || !/^[a-f0-9]{64}$/.test(entry?.sha256) || seen.has(entry.path)) {
|
|
377
|
+
integrityErrors.push("invalid, duplicate, or unsafe managed manifest entry");
|
|
378
|
+
continue;
|
|
379
|
+
}
|
|
380
|
+
seen.add(entry.path);
|
|
381
|
+
if (!exists(target) || !fs.statSync(target).isFile()) integrityErrors.push(`missing managed file: ${entry.path}`);
|
|
382
|
+
else if (sha256(target) !== entry.sha256) integrityErrors.push(`modified managed file: ${entry.path}`);
|
|
383
|
+
}
|
|
384
|
+
if (manifest?.skill_version !== pkg.version) currentErrors.push(`installed version ${manifest?.skill_version || "unknown"} differs from CLI ${pkg.version}`);
|
|
385
|
+
if (manifest?.schema_version !== 3) currentErrors.push("managed manifest schema needs refresh");
|
|
386
|
+
const expected = expectedEntries();
|
|
387
|
+
const expectedPaths = new Set(expected.map(entry => entry.path));
|
|
388
|
+
for (const entry of expected) {
|
|
389
|
+
const recorded = entries.find(item => item?.path === entry.path);
|
|
390
|
+
if (!recorded || recorded.sha256 !== entry.sha256 || recorded.ownership !== "managed") currentErrors.push(`manifest differs from current asset: ${entry.path}`);
|
|
391
|
+
const target = managedTarget(root, entry.path);
|
|
392
|
+
if (!target || !exists(target) || !fs.statSync(target).isFile() || sha256(target) !== entry.sha256) currentErrors.push(`installed file differs from current asset: ${entry.path}`);
|
|
393
|
+
}
|
|
178
394
|
for (const entry of entries) {
|
|
179
|
-
|
|
180
|
-
if (!exists(target)) errors.push(`missing managed file: ${entry.path}`);
|
|
181
|
-
else if (sha256(target) !== entry.sha256) errors.push(`modified managed file: ${entry.path}`);
|
|
395
|
+
if (safeRelativePath(entry?.path) && !expectedPaths.has(entry.path)) currentErrors.push(`obsolete managed entry: ${entry.path}`);
|
|
182
396
|
}
|
|
397
|
+
const skill = managedTarget(root, ".agents/skills/auto-coding-skill");
|
|
398
|
+
const extra = skill && exists(skill) && fs.statSync(skill).isDirectory()
|
|
399
|
+
? listFiles(skill).map(file => `.agents/skills/auto-coding-skill/${file}`).filter(file => !expectedPaths.has(file)) : [];
|
|
400
|
+
currentErrors.push(...extra.map(file => `unexpected installed skill file: ${file}`));
|
|
401
|
+
const legacy = legacyFiles(root, manifest);
|
|
402
|
+
currentErrors.push(...legacy.map(file => `legacy workflow file requires review: ${file}`));
|
|
403
|
+
const errors = [...integrityErrors, ...currentErrors];
|
|
183
404
|
const documents = Object.fromEntries(bootstrapDocs.map(([, target]) => [target, exists(path.join(root, target))]));
|
|
184
|
-
return { project: root, version: manifest?.skill_version || "",
|
|
405
|
+
return { project: root, version: manifest?.skill_version || "", expected_version: pkg.version,
|
|
406
|
+
integrity: integrityErrors.length === 0, current: currentErrors.length === 0, ok: errors.length === 0,
|
|
407
|
+
errors, legacy_files: legacy, unexpected_files: extra, documents };
|
|
185
408
|
}
|
|
186
409
|
|
|
187
410
|
function help() {
|
|
188
|
-
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.`);
|
|
189
412
|
}
|
|
190
413
|
|
|
191
414
|
const args = parseArgs(process.argv);
|
|
192
415
|
if (args.command === "help") help();
|
|
193
|
-
else if (args.command === "init")
|
|
416
|
+
else if (args.command === "init") installProjects([args.dest || process.cwd()], args);
|
|
194
417
|
else if (args.command === "sync") {
|
|
195
418
|
const projects = args.projects.length ? args.projects : [process.cwd()];
|
|
196
|
-
|
|
419
|
+
installProjects(projects, args);
|
|
197
420
|
} else if (args.command === "status") {
|
|
198
421
|
const projects = args.projects.length ? args.projects : [process.cwd()];
|
|
199
422
|
const results = projects.map(status);
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@elvis1513/auto-coding-skill",
|
|
3
|
-
"version": "5.0
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "5.1.0",
|
|
4
|
+
"description": "Lightweight engineering guidance and a managed installer that preserves project-owned documentation.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
7
7
|
"autocoding": "cli/src/index.js"
|
|
@@ -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",
|
|
@@ -31,9 +31,9 @@
|
|
|
31
31
|
"agents",
|
|
32
32
|
"skill",
|
|
33
33
|
"documentation",
|
|
34
|
-
"engineering-
|
|
34
|
+
"engineering-guidance",
|
|
35
35
|
"environment-notes",
|
|
36
|
-
"
|
|
36
|
+
"project-context"
|
|
37
37
|
],
|
|
38
38
|
"repository": {
|
|
39
39
|
"type": "git",
|