@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.
@@ -1,17 +1,20 @@
1
1
  ---
2
2
  name: auto-coding-skill
3
- description: Generic .agents engineering workflow with adaptive micro, standard, and high-risk execution profiles; minimal project scaffold; dev and verified closure modes.
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 a disciplined task → design → implementation → verification
9
- → closure workflow. The project keeps one manual configuration source:
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
- Use subagents only when work is independent and the runtime supports them.
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; changed gate; dev closure.
46
- - `standard`: ordinary feature or defect work; standard gate; dev closure.
47
- - `high-risk`: DB, auth, payment, deployment/build configuration, declared full
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
- High-risk signals cannot be manually downgraded. A full gate must use
51
- `commands.gate_full` or `commands.full_gate`; light/standard fallbacks do not
52
- count. An explicit non-auto configured profile replaces auto's low/normal
53
- baseline but cannot suppress high-risk signals. CI/Jenkins and target
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
- python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
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
- ## Development closure
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
- 1. Locate the real entry point, call chain, existing owner module, tests, and
67
- reusable helpers.
68
- 2. Update the active task with the smallest useful design note.
69
- 3. Create DD/ADR only for cross-module, API, DB, deployment/CI, security, key UI
70
- flow, or lasting structural decisions.
71
- 4. Implement only necessary changes.
72
- 5. Run the resolved gate.
73
- 6. Record `DEV-CLOSED`, commit, push, and stop.
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
- ## Verified closure
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
- High-risk or explicitly verified work uses the strongest path:
146
+ ## Development closure
78
147
 
79
- 1. Run the real full local gate.
80
- 2. Commit and push.
81
- 3. Verify enabled CI/Jenkins and target-environment surfaces.
82
- 4. Record `PASS`, `FAIL`, or `PARTIAL` only from executed evidence.
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` recommends only roles justified by the effective profile:
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
- The main agent owns framing, architecture decisions, integration, verification,
112
- closure records, and Git state.
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/CI state: GitHub connector; local Git for local changes and pushes.
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
- - Secrets: use configured environment references or secure platform flows; do
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 commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
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