@elvis1513/auto-coding-skill 2.2.1 → 3.0.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 +75 -0
- package/cli/assets/skill/SKILL.md +60 -7
- package/cli/assets/skill/data/templates/ENGINEERING.md +75 -5
- package/cli/assets/skill/scripts/ap.py +2413 -99
- package/cli/src/index.js +12 -0
- package/cli/tests/ap_concurrency_test.py +1257 -0
- package/cli/tests/ap_profiles_test.py +1 -0
- package/cli/tests/index.test.js +2 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -4,6 +4,22 @@ A generic `.agents` engineering workflow with adaptive execution profiles,
|
|
|
4
4
|
minimal project scaffolding, evidence-backed closure, and optional CI/Jenkins and
|
|
5
5
|
target-environment verification.
|
|
6
6
|
|
|
7
|
+
## What changed in v3.0.0
|
|
8
|
+
|
|
9
|
+
- Isolated every write task in a registered Git worktree and task branch.
|
|
10
|
+
- Added `task-start`, `task-status`, `task-submodule-sync`, `task-integrate`,
|
|
11
|
+
`task-finish`, and `task-prune` lifecycle commands.
|
|
12
|
+
- Made `commit-push` validate the task manifest before any gate or ledger write,
|
|
13
|
+
stage only the task worktree's exact paths, and detect gate-time mutations.
|
|
14
|
+
- Added task-scoped active, closure, and evidence records to avoid shared append
|
|
15
|
+
conflicts.
|
|
16
|
+
- Serialized target-branch integration and re-ran the resolved gate after
|
|
17
|
+
updating to the latest remote target.
|
|
18
|
+
- Automatically removed integrated worktrees and local task branches, with safe
|
|
19
|
+
lease-based remote task-branch cleanup and merged-branch pruning.
|
|
20
|
+
- Kept `concurrency.isolation: legacy` only as an explicit compatibility escape
|
|
21
|
+
hatch; missing configuration now defaults to worktree isolation.
|
|
22
|
+
|
|
7
23
|
## What changed in v2.2.1
|
|
8
24
|
|
|
9
25
|
- Made same-period ledger archiving update one cumulative archive-index entry
|
|
@@ -93,6 +109,59 @@ python3 docs/tools/autopipeline/ap.py impact --scope auto --json
|
|
|
93
109
|
Each result includes the effective profile, mode, gate scope, reasons, required
|
|
94
110
|
verification surfaces, and recommended Agent roles.
|
|
95
111
|
|
|
112
|
+
## Parallel write isolation
|
|
113
|
+
|
|
114
|
+
Each task that may write files runs in its own registered Git worktree and
|
|
115
|
+
`codex/` task branch. Read-only discovery may remain in the primary worktree.
|
|
116
|
+
|
|
117
|
+
```yaml
|
|
118
|
+
concurrency:
|
|
119
|
+
isolation: worktree
|
|
120
|
+
base_ref: origin/dev
|
|
121
|
+
target_branch: dev
|
|
122
|
+
branch_prefix: codex/
|
|
123
|
+
worktree_root: ../.worktrees
|
|
124
|
+
cleanup_merged: true
|
|
125
|
+
delete_remote_branch: true
|
|
126
|
+
disposable_ignored: []
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
python3 docs/tools/autopipeline/ap.py task-start T0001
|
|
131
|
+
# Continue in the worktree path printed by task-start.
|
|
132
|
+
python3 docs/tools/autopipeline/ap.py task-status T0001
|
|
133
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync T0001
|
|
134
|
+
python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
|
|
135
|
+
python3 docs/tools/autopipeline/ap.py task-integrate T0001
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`commit-push` runs only inside the task worktree recorded in the repository
|
|
139
|
+
manifest and stages only that task's changes. Unknown changes stop the command;
|
|
140
|
+
the workflow never restores, resets, stashes, or cleans them.
|
|
141
|
+
|
|
142
|
+
Successful integration removes the clean worktree and merged local branch, and
|
|
143
|
+
deletes the merged remote task branch by default. `task-finish T0001` retries
|
|
144
|
+
cleanup for one integrated task; `task-prune` removes registered merged tasks
|
|
145
|
+
left behind. Dirty worktrees and unmerged branches are never removed. Integration
|
|
146
|
+
does not update the primary checkout; pull it explicitly when its local state is
|
|
147
|
+
ready. Cleanup also refuses unknown ignored files such as local secrets; list
|
|
148
|
+
only disposable project cache/build paths under `concurrency.disposable_ignored`.
|
|
149
|
+
Initialized submodules are recursively checked before forced task-worktree
|
|
150
|
+
removal: they must be clean and contain no unknown ignored data, local-only
|
|
151
|
+
commits, unmirrored local branches, or additional linked worktrees. Their
|
|
152
|
+
remotes are refreshed before that decision. A durable snapshot
|
|
153
|
+
of refs and reflog commits is stored under Git's
|
|
154
|
+
`auto-coding-skill/submodule-recovery` state before forced worktree removal, so
|
|
155
|
+
a remote deletion race cannot destroy the last copy of a commit. Cleanup never
|
|
156
|
+
deinitializes the primary checkout's shared submodule configuration.
|
|
157
|
+
`task-start` enables Git worktree-scoped config and seeds each task's submodule
|
|
158
|
+
URLs. After changing `.gitmodules`, run `task-submodule-sync` before initializing
|
|
159
|
+
or syncing modules. Relative URLs follow Git's current-worktree default-remote
|
|
160
|
+
rules, including task bases whose `.gitmodules` differs from the control checkout.
|
|
161
|
+
Shared/common submodule config changes are reported and never overwritten.
|
|
162
|
+
Residual Git directories from modules manually deinitialized inside a task block
|
|
163
|
+
forced cleanup until they are reinitialized or recovered.
|
|
164
|
+
|
|
96
165
|
## Gate configuration
|
|
97
166
|
|
|
98
167
|
```yaml
|
|
@@ -199,9 +268,15 @@ python3 docs/tools/autopipeline/ap.py doctor
|
|
|
199
268
|
python3 docs/tools/autopipeline/ap.py classify --scope auto
|
|
200
269
|
python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
|
|
201
270
|
python3 docs/tools/autopipeline/ap.py structure-check --scope auto
|
|
271
|
+
python3 docs/tools/autopipeline/ap.py task-start T0001
|
|
272
|
+
python3 docs/tools/autopipeline/ap.py task-status T0001
|
|
273
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync T0001
|
|
202
274
|
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
203
275
|
python3 docs/tools/autopipeline/ap.py gate-profile
|
|
204
276
|
python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
|
|
277
|
+
python3 docs/tools/autopipeline/ap.py task-integrate T0001
|
|
278
|
+
python3 docs/tools/autopipeline/ap.py task-finish T0001
|
|
279
|
+
python3 docs/tools/autopipeline/ap.py task-prune
|
|
205
280
|
```
|
|
206
281
|
|
|
207
282
|
## Upgrade and multi-project sync
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: auto-coding-skill
|
|
3
|
-
description: Generic .agents engineering workflow with
|
|
3
|
+
description: Generic .agents engineering workflow with isolated Git worktrees for parallel write tasks, adaptive micro/standard/high-risk profiles, minimal project scaffolding, safe integration and branch cleanup, and evidence-backed dev or verified closure.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Auto Coding Skill
|
|
@@ -61,16 +61,62 @@ python3 docs/tools/autopipeline/ap.py classify --scope auto
|
|
|
61
61
|
python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
+
## Parallel write isolation
|
|
65
|
+
|
|
66
|
+
Every task that may write files must use its own registered Git worktree and
|
|
67
|
+
task branch. Read-only discovery may stay in the primary worktree.
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
|
|
71
|
+
# Continue in the worktree path printed by task-start.
|
|
72
|
+
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
73
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
74
|
+
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
|
|
75
|
+
python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`task-start` records the base revision, target branch, task branch, and worktree
|
|
79
|
+
in the repository manifest. `commit-push` is valid only inside that task's
|
|
80
|
+
registered worktree and may stage only changes owned by that task. If unknown
|
|
81
|
+
changes appear, stop and report them. Never restore, reset, stash, clean, or
|
|
82
|
+
otherwise modify another task's or the user's changes.
|
|
83
|
+
|
|
84
|
+
After a successful integration, remove the clean worktree and merged local task
|
|
85
|
+
branch. Delete the merged remote task branch by default. Use `task-finish` to
|
|
86
|
+
retry cleanup for one integrated task and `task-prune` to clean registered merged
|
|
87
|
+
tasks in bulk. Refuse cleanup when a worktree is dirty or a branch is unmerged.
|
|
88
|
+
Do not update the primary checkout during integration; pull it explicitly when
|
|
89
|
+
its user-owned state is ready. Treat unknown ignored files as user data and
|
|
90
|
+
block cleanup; allow only explicitly disposable cache/build paths. Before a
|
|
91
|
+
forced task-worktree removal, recursively require every initialized submodule
|
|
92
|
+
to be clean and contain no unknown ignored data, local-only history, or
|
|
93
|
+
unmirrored local branch. Block cleanup when the submodule has another linked
|
|
94
|
+
worktree or its remotes cannot be refreshed. Before the validated forced removal,
|
|
95
|
+
persist its refs and reflog commits in the Git common directory's managed
|
|
96
|
+
submodule-recovery store so a remote race cannot erase the final copy. Never run
|
|
97
|
+
submodule deinit from a linked task worktree because its shared config can alter
|
|
98
|
+
the primary checkout.
|
|
99
|
+
|
|
100
|
+
`task-start` enables Git worktree-scoped config and seeds task-local submodule
|
|
101
|
+
URLs. After editing `.gitmodules`, run `task-submodule-sync` before submodule
|
|
102
|
+
initialization or sync. Resolve relative URLs with Git's current-worktree
|
|
103
|
+
default-remote semantics, not the integration remote. If shared/common submodule
|
|
104
|
+
config differs from the task-start snapshot, stop and report it without restoring
|
|
105
|
+
or overwriting the value. Treat residual module Git directories from a manual
|
|
106
|
+
deinit/removal as user data: block forced cleanup until they are reinitialized or
|
|
107
|
+
explicitly recovered.
|
|
108
|
+
|
|
64
109
|
## Development closure
|
|
65
110
|
|
|
66
|
-
1.
|
|
111
|
+
1. Start the write task with `task-start` and enter its registered worktree.
|
|
112
|
+
2. Locate the real entry point, call chain, existing owner module, tests, and
|
|
67
113
|
reusable helpers.
|
|
68
|
-
|
|
69
|
-
|
|
114
|
+
3. Update the active task with the smallest useful design note.
|
|
115
|
+
4. Create DD/ADR only for cross-module, API, DB, deployment/CI, security, key UI
|
|
70
116
|
flow, or lasting structural decisions.
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
117
|
+
5. Implement only necessary changes.
|
|
118
|
+
6. Run the resolved gate.
|
|
119
|
+
7. Record `DEV-CLOSED`, commit, push, integrate, and clean the task worktree.
|
|
74
120
|
|
|
75
121
|
## Verified closure
|
|
76
122
|
|
|
@@ -80,6 +126,7 @@ High-risk or explicitly verified work uses the strongest path:
|
|
|
80
126
|
2. Commit and push.
|
|
81
127
|
3. Verify enabled CI/Jenkins and target-environment surfaces.
|
|
82
128
|
4. Record `PASS`, `FAIL`, or `PARTIAL` only from executed evidence.
|
|
129
|
+
5. Integrate successful work and clean its temporary worktree and branches.
|
|
83
130
|
|
|
84
131
|
## Structure policy
|
|
85
132
|
|
|
@@ -130,7 +177,13 @@ python3 docs/tools/autopipeline/ap.py scaffold all --write
|
|
|
130
177
|
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
131
178
|
python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
|
|
132
179
|
python3 docs/tools/autopipeline/ap.py gate-profile
|
|
180
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
|
|
181
|
+
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
182
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
133
183
|
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
|
|
184
|
+
python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
|
|
185
|
+
python3 docs/tools/autopipeline/ap.py task-finish <TASK_ID>
|
|
186
|
+
python3 docs/tools/autopipeline/ap.py task-prune
|
|
134
187
|
```
|
|
135
188
|
|
|
136
189
|
`status` and `sync` manage only the minimal required scaffold. Existing optional
|
|
@@ -8,6 +8,16 @@ project:
|
|
|
8
8
|
repo_root: "."
|
|
9
9
|
stack: "generic"
|
|
10
10
|
|
|
11
|
+
concurrency:
|
|
12
|
+
isolation: "worktree"
|
|
13
|
+
base_ref: ""
|
|
14
|
+
target_branch: ""
|
|
15
|
+
branch_prefix: "codex/"
|
|
16
|
+
worktree_root: "../.worktrees"
|
|
17
|
+
cleanup_merged: true
|
|
18
|
+
delete_remote_branch: true
|
|
19
|
+
disposable_ignored: []
|
|
20
|
+
|
|
11
21
|
commands:
|
|
12
22
|
gate_changed: ""
|
|
13
23
|
gate_standard: ""
|
|
@@ -84,6 +94,9 @@ docs:
|
|
|
84
94
|
taskbook: "docs/tasks/taskbook.md"
|
|
85
95
|
closure_log: "docs/tasks/closure-log.md"
|
|
86
96
|
evidence_log: "docs/tasks/evidence.jsonl"
|
|
97
|
+
active_task_dir: "docs/tasks/active"
|
|
98
|
+
task_closure_dir: "docs/tasks/closures"
|
|
99
|
+
task_evidence_dir: "docs/tasks/evidence"
|
|
87
100
|
design_dir: "docs/design"
|
|
88
101
|
task_archive_dir: "docs/tasks/archives"
|
|
89
102
|
design_archive_dir: "docs/archive/design"
|
|
@@ -135,6 +148,15 @@ Required for normal development:
|
|
|
135
148
|
- `workflow.mode`: `dev` or `verify`
|
|
136
149
|
- `workflow.profile`: `auto`, `micro`, `standard`, or `high-risk`
|
|
137
150
|
- `project.name`
|
|
151
|
+
- `concurrency.isolation`: keep `worktree` for every task that may write files
|
|
152
|
+
- `concurrency.base_ref` and `target_branch`: leave blank to derive the current
|
|
153
|
+
upstream, or set them explicitly for a fixed integration branch
|
|
154
|
+
- `concurrency.branch_prefix` and `worktree_root`
|
|
155
|
+
- `concurrency.cleanup_merged` and `delete_remote_branch`: keep both enabled to
|
|
156
|
+
remove integrated temporary worktrees and branches
|
|
157
|
+
- `concurrency.disposable_ignored`: add only project-specific ignored cache/build
|
|
158
|
+
paths that may be discarded with a task worktree; ignored secrets and unknown
|
|
159
|
+
paths block cleanup, including inside initialized submodules
|
|
138
160
|
- at least one usable gate command; configure all three gate commands when the
|
|
139
161
|
project can exercise changed, standard, and full scopes
|
|
140
162
|
- `verification.target_env_required` and `verification.jenkins_required`
|
|
@@ -149,16 +171,57 @@ enabled, add `jenkins` with its base/job URLs, branch, artifact/deploy metadata,
|
|
|
149
171
|
timeout, UI/API users, and password values or environment references. Unused
|
|
150
172
|
sections should remain absent rather than filled with placeholders.
|
|
151
173
|
|
|
174
|
+
## Concurrent write tasks
|
|
175
|
+
|
|
176
|
+
Run every write task in a registered Git worktree and task branch. Do not share
|
|
177
|
+
the primary worktree between writers.
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
|
|
181
|
+
# Enter the worktree path printed by task-start.
|
|
182
|
+
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
183
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
184
|
+
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
|
|
185
|
+
python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
`task-start` fixes the task's base revision and records its task branch and
|
|
189
|
+
worktree in the repository manifest. Run `commit-push` only from that registered
|
|
190
|
+
worktree. Stage only task-owned paths. If an unknown change appears, stop and
|
|
191
|
+
report it; never restore, reset, stash, clean, or otherwise alter it.
|
|
192
|
+
|
|
193
|
+
Successful integration removes the clean worktree and merged local branch, and
|
|
194
|
+
deletes the merged remote task branch by default. Use `task-finish <TASK_ID>` to
|
|
195
|
+
retry cleanup for one integrated task and `task-prune` for registered merged
|
|
196
|
+
tasks left behind. Cleanup must refuse dirty worktrees and unmerged branches.
|
|
197
|
+
Before forced task-worktree removal, recursively require initialized submodules
|
|
198
|
+
to be clean and contain no unknown ignored data, local-only history, or
|
|
199
|
+
unmirrored local branches. A submodule with another linked worktree or an
|
|
200
|
+
unrefreshable remote blocks cleanup. Before forced worktree removal, persist its
|
|
201
|
+
refs and reflog commits in the managed Git-common-dir submodule recovery store.
|
|
202
|
+
Do not run submodule deinit from a linked task worktree because its shared config
|
|
203
|
+
can alter the primary checkout.
|
|
204
|
+
`task-start` enables worktree-scoped Git config and seeds task-local submodule
|
|
205
|
+
URLs. After changing `.gitmodules`, run `task-submodule-sync` before submodule
|
|
206
|
+
initialization or sync. Resolve relative URLs with Git's current-worktree
|
|
207
|
+
default-remote semantics. If shared/common submodule config changed after task
|
|
208
|
+
start, report and stop without restoring or overwriting it. Residual module Git
|
|
209
|
+
directories from a manual deinit or removal block forced cleanup until they are
|
|
210
|
+
reinitialized or recovered.
|
|
211
|
+
Integration must not update the primary checkout; pull it explicitly only when
|
|
212
|
+
its user-owned state is ready.
|
|
213
|
+
|
|
152
214
|
## Default workflow
|
|
153
215
|
|
|
154
216
|
Development:
|
|
155
217
|
|
|
156
218
|
1. Read this file and the active task entry.
|
|
157
|
-
2.
|
|
158
|
-
3.
|
|
159
|
-
4.
|
|
160
|
-
5.
|
|
161
|
-
6.
|
|
219
|
+
2. Start the write task with `task-start` and enter its registered worktree.
|
|
220
|
+
3. Run or reason through `classify --scope auto`.
|
|
221
|
+
4. Record the smallest useful design note; create DD/ADR only when indicated.
|
|
222
|
+
5. Implement the necessary change using existing project structure and reuse points.
|
|
223
|
+
6. Run the resolved profile gate.
|
|
224
|
+
7. Record `DEV-CLOSED`, commit, push, integrate, and clean the task worktree.
|
|
162
225
|
|
|
163
226
|
High-risk or explicit verification:
|
|
164
227
|
|
|
@@ -166,6 +229,7 @@ High-risk or explicit verification:
|
|
|
166
229
|
2. Commit and push.
|
|
167
230
|
3. Verify enabled CI/Jenkins and target-environment surfaces.
|
|
168
231
|
4. Record `PASS`, `FAIL`, or `PARTIAL` from actual evidence.
|
|
232
|
+
5. Integrate successful work and clean its temporary worktree and branches.
|
|
169
233
|
|
|
170
234
|
The authoritative order remains ENGINEERING, taskbook/archives, design and
|
|
171
235
|
interface records, regression/bug records, closure evidence, deployment records,
|
|
@@ -210,7 +274,13 @@ python3 docs/tools/autopipeline/ap.py doctor
|
|
|
210
274
|
python3 docs/tools/autopipeline/ap.py classify --scope auto
|
|
211
275
|
python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
|
|
212
276
|
python3 docs/tools/autopipeline/ap.py structure-check --scope auto
|
|
277
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
|
|
278
|
+
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
279
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
213
280
|
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
|
|
281
|
+
python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
|
|
282
|
+
python3 docs/tools/autopipeline/ap.py task-finish <TASK_ID>
|
|
283
|
+
python3 docs/tools/autopipeline/ap.py task-prune
|
|
214
284
|
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
215
285
|
python3 docs/tools/autopipeline/ap.py gate-profile
|
|
216
286
|
```
|