@elvis1513/auto-coding-skill 2.2.1 → 3.0.1
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 +178 -46
- package/cli/assets/agents/browser-debugger.toml +5 -7
- package/cli/assets/agents/docs-researcher.toml +3 -5
- package/cli/assets/agents/explorer.toml +5 -10
- package/cli/assets/agents/fixer.toml +19 -17
- package/cli/assets/agents/reviewer.toml +14 -10
- package/cli/assets/skill/SKILL.md +152 -37
- package/cli/assets/skill/data/contracts/orchestration-v1.schema.json +475 -0
- package/cli/assets/skill/data/templates/ENGINEERING.md +226 -74
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +4 -4
- package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +7 -6
- package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +11 -4
- package/cli/assets/skill/scripts/ap.py +3296 -545
- package/cli/src/index.js +411 -51
- package/cli/tests/ap_concurrency_test.py +1578 -0
- package/cli/tests/ap_profiles_test.py +242 -98
- package/cli/tests/index.test.js +410 -15
- package/package.json +4 -4
|
@@ -1,17 +1,20 @@
|
|
|
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, fast changed-scope local gates, push-based completion, required project access configuration, safe integration, and branch cleanup.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Auto Coding Skill
|
|
7
7
|
|
|
8
|
-
Use this skill for
|
|
9
|
-
→
|
|
8
|
+
Use this skill for an analysis → decomposition → design → development → fast
|
|
9
|
+
gate → push workflow. The project keeps one manual configuration source:
|
|
10
10
|
`docs/ENGINEERING.md`.
|
|
11
11
|
|
|
12
12
|
At task start, inventory installed skills, MCP servers, connectors, browser
|
|
13
13
|
tools, and repository scripts. Prefer the most direct authoritative capability.
|
|
14
|
-
|
|
14
|
+
The main agent decomposes the task before dispatch. Run independent read-only
|
|
15
|
+
discovery roles in parallel when the runtime supports them. Assign each
|
|
16
|
+
independent write unit to exactly one fixer in its own registered worktree;
|
|
17
|
+
never share a write worktree between agents.
|
|
15
18
|
|
|
16
19
|
## Install and upgrade
|
|
17
20
|
|
|
@@ -36,50 +39,133 @@ python3 docs/tools/autopipeline/ap.py upgrade --write
|
|
|
36
39
|
|
|
37
40
|
Upgrade preserves project documents, custom agents, and explicit local model
|
|
38
41
|
overrides. Managed agents without a `model` inherit the current client model.
|
|
42
|
+
Initialization is incomplete until every URL, username, and direct password under
|
|
43
|
+
`access.*` is filled in `docs/ENGINEERING.md` and `doctor` passes.
|
|
39
44
|
|
|
40
45
|
## Configuration and profiles
|
|
41
46
|
|
|
42
47
|
Read `docs/ENGINEERING.md` before choosing a path. `workflow.profile: auto`
|
|
43
48
|
resolves to exactly one execution profile:
|
|
44
49
|
|
|
45
|
-
- `micro`: docs/tests-only or isolated low-risk work
|
|
46
|
-
- `standard`: ordinary feature or defect work
|
|
47
|
-
- `high-risk`: DB, auth, payment, deployment/build
|
|
48
|
-
rules, or explicit verify work; real full gate; verify closure.
|
|
50
|
+
- `micro`: docs/tests-only or isolated low-risk work.
|
|
51
|
+
- `standard`: ordinary feature or defect work.
|
|
52
|
+
- `high-risk`: DB, auth, payment, deployment/build, or broad structural work.
|
|
49
53
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
verification remain controlled by `verification.*_required`.
|
|
54
|
+
Use profiles only to adjust analysis, design depth, and reviewer recommendations.
|
|
55
|
+
Run exactly one changed-scope fast local gate for every profile. Keep standard/full
|
|
56
|
+
regression, structure scans, Docker, API verification, Jenkins, deployment, and
|
|
57
|
+
target checks as explicit diagnostics outside the default development flow.
|
|
55
58
|
|
|
56
|
-
Run:
|
|
59
|
+
Run the configuration and impact preflight:
|
|
57
60
|
|
|
58
61
|
```bash
|
|
59
62
|
python3 docs/tools/autopipeline/ap.py doctor
|
|
60
63
|
python3 docs/tools/autopipeline/ap.py classify --scope auto
|
|
61
|
-
|
|
64
|
+
# Before development, add repeatable --planned-path values and either --intent
|
|
65
|
+
# or --intent-file when the working tree does not yet describe the task.
|
|
62
66
|
```
|
|
63
67
|
|
|
64
|
-
|
|
68
|
+
`light-gate` remains available for an explicit gate-diagnostic task. Do not run
|
|
69
|
+
it before normal `commit-push`; `commit-push` owns the single automatic gate.
|
|
65
70
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
71
|
+
## Parallel write isolation
|
|
72
|
+
|
|
73
|
+
Every task that may write files must use its own registered Git worktree and
|
|
74
|
+
task branch. Read-only discovery may stay in the primary worktree. A registered
|
|
75
|
+
worktree has exactly one writer. The main agent and other fixers must not edit it
|
|
76
|
+
while its owning fixer is active.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID> \
|
|
80
|
+
--owned-path <PATH> --depends-on <TASK_ID=SHA> --writer <WRITER>
|
|
81
|
+
# Continue in the worktree path printed by task-start.
|
|
82
|
+
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
83
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
84
|
+
python3 docs/tools/autopipeline/ap.py task-review <TASK_ID> \
|
|
85
|
+
--verdict approved --diff-fingerprint <SHA256> --reviewer <REVIEWER>
|
|
86
|
+
python3 docs/tools/autopipeline/ap.py task-handoff <TASK_ID> \
|
|
87
|
+
--from <WRITER> --to <WRITER> [--generation <N>]
|
|
88
|
+
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> \
|
|
89
|
+
--msg "<TASK_ID>: <summary>" [--writer <WRITER>]
|
|
90
|
+
python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
|
|
91
|
+
# After resolving an integration rebase conflict:
|
|
92
|
+
python3 docs/tools/autopipeline/ap.py task-resume <TASK_ID>
|
|
93
|
+
```
|
|
74
94
|
|
|
75
|
-
|
|
95
|
+
`task-start` records the base revision, target branch, task branch, worktree,
|
|
96
|
+
owned paths, prerequisite task SHAs, and writer lease in the repository manifest.
|
|
97
|
+
Pass one `--owned-path` per owned path and one `--depends-on TASK_ID=SHA` per
|
|
98
|
+
prerequisite. The writer defaults to `CODEX_THREAD_ID`; pass `--writer` only when
|
|
99
|
+
an explicit stable identity is needed. Use `task-handoff` for an intentional
|
|
100
|
+
lease transfer; its generation check prevents a stale writer from reclaiming the
|
|
101
|
+
task. `commit-push` is valid only for the active writer inside the registered
|
|
102
|
+
worktree and may stage only owned paths. If unknown changes appear, stop and
|
|
103
|
+
report them. Never restore, reset, stash, clean, or otherwise modify another
|
|
104
|
+
task's or the user's changes.
|
|
105
|
+
|
|
106
|
+
After a reviewer returns, the main agent records the verdict and exact 64-character
|
|
107
|
+
diff fingerprint with `task-review`. Any content change invalidates that review.
|
|
108
|
+
`commit-push` and `task-integrate` require a current approval for the current
|
|
109
|
+
fingerprint and verify prerequisite SHAs. If integration enters a rebase conflict,
|
|
110
|
+
resolve it in the registered worktree, continue or abort the rebase as instructed,
|
|
111
|
+
then run `task-resume`; do not bypass the conflicted manifest state.
|
|
112
|
+
|
|
113
|
+
Treat `commit-push` plus `task-integrate` as one push stage. Run the fast gate
|
|
114
|
+
only in `commit-push`; integration fetches/rebases, safely pushes the target, and
|
|
115
|
+
cleans the task without repeating the gate. Successful target push ends the
|
|
116
|
+
coding task. Do not wait for or inspect Jenkins/build/deploy results afterward.
|
|
117
|
+
The task commit runs project commit hooks once. The internal backup task-branch
|
|
118
|
+
push skips the pre-push hook; the final target-branch push runs it once.
|
|
119
|
+
Integration creates no second evidence commit.
|
|
120
|
+
|
|
121
|
+
After a successful integration, remove the clean worktree and merged local task
|
|
122
|
+
branch. Delete the merged remote task branch by default. Use `task-finish` to
|
|
123
|
+
retry cleanup for one integrated task and `task-prune` to clean registered merged
|
|
124
|
+
tasks in bulk. Refuse cleanup when a worktree is dirty or a branch is unmerged.
|
|
125
|
+
Do not update the primary checkout during integration; pull it explicitly when
|
|
126
|
+
its user-owned state is ready. Treat unknown ignored files as user data and
|
|
127
|
+
block cleanup; allow only explicitly disposable cache/build paths. Before a
|
|
128
|
+
forced task-worktree removal, recursively require every initialized submodule
|
|
129
|
+
to be clean and contain no unknown ignored data, local-only history, or
|
|
130
|
+
unmirrored local branch. Block cleanup when the submodule has another linked
|
|
131
|
+
worktree or its remotes cannot be refreshed. Before the validated forced removal,
|
|
132
|
+
persist its refs and reflog commits in the Git common directory's managed
|
|
133
|
+
submodule-recovery store so a remote race cannot erase the final copy. Never run
|
|
134
|
+
submodule deinit from a linked task worktree because its shared config can alter
|
|
135
|
+
the primary checkout.
|
|
136
|
+
|
|
137
|
+
`task-start` enables Git worktree-scoped config and seeds task-local submodule
|
|
138
|
+
URLs. After editing `.gitmodules`, run `task-submodule-sync` before submodule
|
|
139
|
+
initialization or sync. Resolve relative URLs with Git's current-worktree
|
|
140
|
+
default-remote semantics, not the integration remote. If shared/common submodule
|
|
141
|
+
config differs from the task-start snapshot, stop and report it without restoring
|
|
142
|
+
or overwriting the value. Treat residual module Git directories from a manual
|
|
143
|
+
deinit/removal as user data: block forced cleanup until they are reinitialized or
|
|
144
|
+
explicitly recovered.
|
|
76
145
|
|
|
77
|
-
|
|
146
|
+
## Development closure
|
|
78
147
|
|
|
79
|
-
1.
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
148
|
+
1. The main agent analyzes and decomposes the request into bounded units with
|
|
149
|
+
explicit dependencies, acceptance criteria, and owned paths.
|
|
150
|
+
2. Run justified `explorer`, `docs_researcher`, and `browser_debugger` discovery
|
|
151
|
+
in parallel, then let the main agent merge their evidence into one design.
|
|
152
|
+
3. Create DD/ADR only for cross-module, API, DB, deployment/CI, security, key UI
|
|
153
|
+
flow, or lasting structural decisions.
|
|
154
|
+
4. Start one registered task worktree per independent write unit and assign one
|
|
155
|
+
fixer to it. Parallelize only dependency-free units with non-overlapping paths;
|
|
156
|
+
deliver implementation → review → gate/integration in dependency waves, and
|
|
157
|
+
start the next wave only after its prerequisites are integrated.
|
|
158
|
+
5. Review each stable diff with a read-only reviewer. Route blocking findings to
|
|
159
|
+
the owning fixer and re-review after any change. The main agent records the
|
|
160
|
+
current verdict with `task-review`, then hands the writer lease back before Git
|
|
161
|
+
closure when required.
|
|
162
|
+
6. After all agents have returned, the main agent runs `commit-push` for each
|
|
163
|
+
write task; it executes the changed-scope fast gate once, records
|
|
164
|
+
`DEV-CLOSED`, commits, and pushes the task branch.
|
|
165
|
+
7. The main agent runs `task-integrate` in dependency order to push the target
|
|
166
|
+
branch and clean every task worktree and merged task branch.
|
|
167
|
+
8. Stop. Jenkins owns later build/deploy work and the project owner owns actual
|
|
168
|
+
acceptance. Ignore later external failures unless the user opens a diagnostic task.
|
|
83
169
|
|
|
84
170
|
## Structure policy
|
|
85
171
|
|
|
@@ -100,7 +186,7 @@ python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
|
|
|
100
186
|
|
|
101
187
|
Role templates provide behavior and permission boundaries, while the active
|
|
102
188
|
client supplies the available model unless a project keeps an explicit override.
|
|
103
|
-
`classify`
|
|
189
|
+
`classify` returns both justified roles and a structured `agent_plan`:
|
|
104
190
|
|
|
105
191
|
- `explorer`: read-only repository discovery and root-cause tracing.
|
|
106
192
|
- `docs_researcher`: current official API/version research.
|
|
@@ -108,8 +194,28 @@ client supplies the available model unless a project keeps an explicit override.
|
|
|
108
194
|
- `fixer`: bounded implementation after scope is clear.
|
|
109
195
|
- `reviewer`: correctness, security, regression, and evidence review.
|
|
110
196
|
|
|
111
|
-
|
|
112
|
-
|
|
197
|
+
For standard and high-risk write tasks, use the following fan-out/fan-in contract:
|
|
198
|
+
|
|
199
|
+
1. The main agent owns decomposition and supplies every subagent with `task_id`,
|
|
200
|
+
role, scope, dependencies, acceptance criteria, and expected output.
|
|
201
|
+
2. Discovery roles are read-only and may run in parallel. Browser work is limited
|
|
202
|
+
to requested reproduction/evidence; it does not replace owner acceptance.
|
|
203
|
+
3. Each fixer receives a task branch, absolute worktree path, and owned paths.
|
|
204
|
+
It may edit only that worktree and must not commit, push, integrate, clean, or
|
|
205
|
+
run the project gate.
|
|
206
|
+
4. Each reviewer receives a stable diff and binds approved or changes-requested
|
|
207
|
+
to its fingerprint. Changes go back to the same fixer and invalidate approval.
|
|
208
|
+
5. Every subagent returns exactly one JSON object conforming to
|
|
209
|
+
`data/contracts/orchestration-v1.schema.json#/$defs/agentResult`, with integer
|
|
210
|
+
`contract_version: 1`. It includes node/task/role, base SHA, dependencies,
|
|
211
|
+
owned and changed paths, diff fingerprint, evidence, findings, verdict, risks,
|
|
212
|
+
and next owner. Read-only roles return no changed paths.
|
|
213
|
+
6. The main agent alone owns architecture decisions, the single fast gate per
|
|
214
|
+
write task, closure records, commits, integration, push, and branch cleanup.
|
|
215
|
+
|
|
216
|
+
Micro tasks stay main-agent-only unless they contain genuinely independent work
|
|
217
|
+
whose benefit exceeds delegation overhead. If subagents are unavailable, the
|
|
218
|
+
main agent executes the same stages sequentially without weakening isolation.
|
|
113
219
|
|
|
114
220
|
## Tool routing
|
|
115
221
|
|
|
@@ -117,11 +223,11 @@ closure records, and Git state.
|
|
|
117
223
|
- Current library/API behavior: official documentation MCP or matching skill.
|
|
118
224
|
- UI: in-app browser for local pages, Chrome for existing logged-in state,
|
|
119
225
|
Playwright for deterministic automation, Computer Use for unsupported native UI.
|
|
120
|
-
- PR/issue
|
|
226
|
+
- PR/issue state: GitHub connector; local Git for local changes and pushes.
|
|
121
227
|
- Design, security, analytics, and document artifacts: use the matching installed
|
|
122
228
|
skill or connector before manual recreation.
|
|
123
|
-
-
|
|
124
|
-
not invent values.
|
|
229
|
+
- Credentials: use the direct values configured under `access.*` in
|
|
230
|
+
`docs/ENGINEERING.md`; do not invent or echo values unnecessarily.
|
|
125
231
|
|
|
126
232
|
## Optional documents and operations
|
|
127
233
|
|
|
@@ -130,7 +236,16 @@ python3 docs/tools/autopipeline/ap.py scaffold all --write
|
|
|
130
236
|
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
131
237
|
python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
|
|
132
238
|
python3 docs/tools/autopipeline/ap.py gate-profile
|
|
133
|
-
python3 docs/tools/autopipeline/ap.py
|
|
239
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID> --owned-path <PATH> [--depends-on <TASK_ID=SHA>] [--writer <WRITER>]
|
|
240
|
+
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
241
|
+
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
242
|
+
python3 docs/tools/autopipeline/ap.py task-review <TASK_ID> --verdict <VERDICT> --diff-fingerprint <SHA256> [--reviewer <REVIEWER>]
|
|
243
|
+
python3 docs/tools/autopipeline/ap.py task-handoff <TASK_ID> --from <WRITER> --to <WRITER> [--generation <N>]
|
|
244
|
+
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>" [--writer <WRITER>]
|
|
245
|
+
python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
|
|
246
|
+
python3 docs/tools/autopipeline/ap.py task-resume <TASK_ID>
|
|
247
|
+
python3 docs/tools/autopipeline/ap.py task-finish <TASK_ID>
|
|
248
|
+
python3 docs/tools/autopipeline/ap.py task-prune
|
|
134
249
|
```
|
|
135
250
|
|
|
136
251
|
`status` and `sync` manage only the minimal required scaffold. Existing optional
|