@elvis1513/auto-coding-skill 3.0.0 → 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 +111 -54
- 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 +111 -49
- package/cli/assets/skill/data/contracts/orchestration-v1.schema.json +475 -0
- package/cli/assets/skill/data/templates/ENGINEERING.md +164 -82
- 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 +1000 -563
- package/cli/src/index.js +399 -51
- package/cli/tests/ap_concurrency_test.py +396 -75
- package/cli/tests/ap_profiles_test.py +242 -99
- package/cli/tests/index.test.js +409 -15
- package/package.json +3 -3
|
@@ -1,17 +1,20 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: auto-coding-skill
|
|
3
|
-
description: Generic .agents engineering workflow with isolated Git worktrees for parallel write tasks,
|
|
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,84 @@ 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
|
|
|
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.
|
|
70
|
+
|
|
64
71
|
## Parallel write isolation
|
|
65
72
|
|
|
66
73
|
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.
|
|
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.
|
|
68
77
|
|
|
69
78
|
```bash
|
|
70
|
-
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
|
|
79
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID> \
|
|
80
|
+
--owned-path <PATH> --depends-on <TASK_ID=SHA> --writer <WRITER>
|
|
71
81
|
# Continue in the worktree path printed by task-start.
|
|
72
82
|
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
73
83
|
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
74
|
-
python3 docs/tools/autopipeline/ap.py
|
|
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>]
|
|
75
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>
|
|
76
93
|
```
|
|
77
94
|
|
|
78
|
-
`task-start` records the base revision, target branch, task branch,
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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.
|
|
83
120
|
|
|
84
121
|
After a successful integration, remove the clean worktree and merged local task
|
|
85
122
|
branch. Delete the merged remote task branch by default. Use `task-finish` to
|
|
@@ -108,25 +145,27 @@ explicitly recovered.
|
|
|
108
145
|
|
|
109
146
|
## Development closure
|
|
110
147
|
|
|
111
|
-
1.
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
|
116
153
|
flow, or lasting structural decisions.
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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.
|
|
130
169
|
|
|
131
170
|
## Structure policy
|
|
132
171
|
|
|
@@ -147,7 +186,7 @@ python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
|
|
|
147
186
|
|
|
148
187
|
Role templates provide behavior and permission boundaries, while the active
|
|
149
188
|
client supplies the available model unless a project keeps an explicit override.
|
|
150
|
-
`classify`
|
|
189
|
+
`classify` returns both justified roles and a structured `agent_plan`:
|
|
151
190
|
|
|
152
191
|
- `explorer`: read-only repository discovery and root-cause tracing.
|
|
153
192
|
- `docs_researcher`: current official API/version research.
|
|
@@ -155,8 +194,28 @@ client supplies the available model unless a project keeps an explicit override.
|
|
|
155
194
|
- `fixer`: bounded implementation after scope is clear.
|
|
156
195
|
- `reviewer`: correctness, security, regression, and evidence review.
|
|
157
196
|
|
|
158
|
-
|
|
159
|
-
|
|
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.
|
|
160
219
|
|
|
161
220
|
## Tool routing
|
|
162
221
|
|
|
@@ -164,11 +223,11 @@ closure records, and Git state.
|
|
|
164
223
|
- Current library/API behavior: official documentation MCP or matching skill.
|
|
165
224
|
- UI: in-app browser for local pages, Chrome for existing logged-in state,
|
|
166
225
|
Playwright for deterministic automation, Computer Use for unsupported native UI.
|
|
167
|
-
- PR/issue
|
|
226
|
+
- PR/issue state: GitHub connector; local Git for local changes and pushes.
|
|
168
227
|
- Design, security, analytics, and document artifacts: use the matching installed
|
|
169
228
|
skill or connector before manual recreation.
|
|
170
|
-
-
|
|
171
|
-
not invent values.
|
|
229
|
+
- Credentials: use the direct values configured under `access.*` in
|
|
230
|
+
`docs/ENGINEERING.md`; do not invent or echo values unnecessarily.
|
|
172
231
|
|
|
173
232
|
## Optional documents and operations
|
|
174
233
|
|
|
@@ -177,11 +236,14 @@ python3 docs/tools/autopipeline/ap.py scaffold all --write
|
|
|
177
236
|
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
178
237
|
python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
|
|
179
238
|
python3 docs/tools/autopipeline/ap.py gate-profile
|
|
180
|
-
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
|
|
239
|
+
python3 docs/tools/autopipeline/ap.py task-start <TASK_ID> --owned-path <PATH> [--depends-on <TASK_ID=SHA>] [--writer <WRITER>]
|
|
181
240
|
python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
|
|
182
241
|
python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
|
|
183
|
-
python3 docs/tools/autopipeline/ap.py
|
|
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>]
|
|
184
245
|
python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
|
|
246
|
+
python3 docs/tools/autopipeline/ap.py task-resume <TASK_ID>
|
|
185
247
|
python3 docs/tools/autopipeline/ap.py task-finish <TASK_ID>
|
|
186
248
|
python3 docs/tools/autopipeline/ap.py task-prune
|
|
187
249
|
```
|