@elvis1513/auto-coding-skill 3.0.4 → 4.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.
@@ -1,265 +1,166 @@
1
1
  ---
2
2
  name: auto-coding-skill
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.
3
+ description: Delivery-first engineering workflow for repository changes. Use for analysis, task decomposition, necessary design, implementation, fast changed-scope validation, safe commit/push, adaptive Git isolation, parallel writer coordination, and temporary branch cleanup. Keep clean single-writer work on the current branch; escalate to worktrees, subagents, review, or stronger affected-scope checks only when risk or concurrency justifies them.
4
4
  ---
5
5
 
6
6
  # Auto Coding Skill
7
7
 
8
- Use this skill for an analysis → decomposition → design → development → fast
9
- gate → push workflow. The project keeps one manual configuration source:
10
- `docs/ENGINEERING.md`.
8
+ ## Activate only useful guardrails
11
9
 
12
- At task start, inventory installed skills, MCP servers, connectors, browser
13
- tools, and repository scripts. Prefer the most direct authoritative capability.
14
- The main agent decomposes the task before dispatch. Run independent read-only
15
- discovery roles in parallel when the runtime supports them. A single serial
16
- writer uses the current branch when its checkout is clean. Dirty checkouts and
17
- parallel writers use one registered worktree per fixer; never share a write
18
- worktree between agents.
10
+ This Skill is a decision aid, not a mandatory ceremony. For each task, use only
11
+ the mechanisms whose expected efficiency or quality benefit exceeds their cost.
12
+ Read-only questions, obvious clean-checkout edits, and terminal ledger maintenance
13
+ need no classify command, machine task lifecycle, design record, reviewer, or
14
+ subagent by default. Repository code changes still receive one real, fast,
15
+ affected-scope validation before commit/push.
19
16
 
20
- ## Install and upgrade
21
-
22
- ```bash
23
- autocoding init
24
- autocoding sync --projects .
25
- pip install pyyaml requests
26
- ```
17
+ Deliver changes through:
27
18
 
28
- New projects receive a minimal scaffold: the project-local skill, managed role
29
- templates, `docs/ENGINEERING.md`, taskbook, closure log, and a small compatibility
30
- launcher. Optional design, API, review, testing, deployment, and bug documents
31
- are created only with `ap.py scaffold <group> --write`.
19
+ `analysis → decomposition → necessary design → development → one final fast
20
+ changed-scope gate → commit/push`.
32
21
 
33
- For existing projects:
34
-
35
- ```bash
36
- autocoding sync --projects .
37
- python3 docs/tools/autopipeline/ap.py upgrade --dry-run
38
- python3 docs/tools/autopipeline/ap.py upgrade --write
39
- ```
22
+ Read the fully managed root `AGENTS.md`, then `docs/ENGINEERING.md` for project
23
+ facts, access values, risk rules, and validation routes. Treat target-branch push
24
+ as normal coding completion. Do not poll Jenkins, deployment, or owner acceptance.
25
+ When the user explicitly asks to diagnose a failure caused by that push, continue
26
+ the diagnosis and repair in the same conversation/task without inventing another
27
+ ledger lifecycle.
40
28
 
41
- Upgrade preserves project documents, custom agents, and explicit local model
42
- overrides. Managed agents without a `model` inherit the current client model.
43
- Initialization is incomplete until every URL, username, and direct password under
44
- `access.*` is filled in `docs/ENGINEERING.md` and `doctor` passes.
29
+ ## Choose the lightest safe path
45
30
 
46
- ## Configuration and profiles
31
+ Inspect the checkout before writing:
47
32
 
48
- Read `docs/ENGINEERING.md` before choosing a path. `workflow.profile: auto`
49
- resolves to exactly one execution profile:
33
+ - Use the current branch for one writer when the checkout is clean.
34
+ - Use an isolated task branch/worktree when unrelated changes already exist,
35
+ when more than one writer will run, or when the project explicitly requires it.
36
+ - Use one writer per worktree and non-overlapping owned paths.
37
+ - Create no temporary branch merely to analyze a task or when no diff is produced.
38
+ - Never restore, reset, stash, clean, or modify unknown user/task changes.
50
39
 
51
- - `micro`: docs/tests-only or isolated low-risk work.
52
- - `standard`: ordinary feature or defect work.
53
- - `high-risk`: DB, auth, payment, deployment/build, or broad structural work.
54
-
55
- Use profiles only to adjust analysis, design depth, and reviewer recommendations.
56
- Run exactly one changed-scope fast local gate for every profile. Keep standard/full
57
- regression, structure scans, Docker, API verification, Jenkins, deployment, and
58
- target checks as explicit diagnostics outside the default development flow.
59
-
60
- Run the configuration and impact preflight:
40
+ Classify planned work before development when impact is unclear:
61
41
 
62
42
  ```bash
63
- python3 docs/tools/autopipeline/ap.py doctor
64
- python3 docs/tools/autopipeline/ap.py classify --scope auto
65
- # Before development, add repeatable --planned-path values and either --intent
66
- # or --intent-file when the working tree does not yet describe the task.
43
+ python3 docs/tools/autopipeline/ap.py classify --scope auto \
44
+ --planned-path <PATH> --intent "<intent>" [--writers <N>]
67
45
  ```
68
46
 
69
- `light-gate` remains available for an explicit gate-diagnostic task. Do not add
70
- it before normal closure. The main agent runs exactly one configured changed
71
- gate directly on a clean serial branch or through `commit-push` for isolated work.
47
+ `execution_mode=direct` means stay on the current branch.
48
+ `execution_mode=isolated` means start registered worktrees. `execution_mode=none`
49
+ means do not create Git state.
72
50
 
73
- ## Adaptive write isolation
74
-
75
- For one serial writer, inspect the current checkout before creating anything. If
76
- it is clean, use its current branch directly. If it already has changes, or two
77
- or more writers will run concurrently, preserve the checkout and use one
78
- registered task branch/worktree per writer. Read-only discovery may stay in the
79
- primary worktree. A worktree has exactly one writer; no other agent may edit it
80
- while that writer is active. The lifecycle commands below are for isolated mode.
51
+ Use the runtime-supported lifecycle when a machine-enforced task boundary helps:
81
52
 
82
53
  ```bash
83
- python3 docs/tools/autopipeline/ap.py task-start <TASK_ID> \
84
- --owned-path <PATH> --depends-on <TASK_ID=SHA> --writer <WRITER>
85
- # Continue in the worktree path printed by task-start.
86
- python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
87
- python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
88
- python3 docs/tools/autopipeline/ap.py task-review <TASK_ID> \
89
- --verdict approved --diff-fingerprint <SHA256> --reviewer <REVIEWER>
90
- python3 docs/tools/autopipeline/ap.py task-handoff <TASK_ID> \
91
- --from <WRITER> --to <WRITER> [--generation <N>]
92
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> \
93
- --msg "<TASK_ID>: <summary>" [--writer <WRITER>]
94
- python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
95
- # After resolving an integration rebase conflict:
96
- python3 docs/tools/autopipeline/ap.py task-resume <TASK_ID>
54
+ python3 docs/tools/autopipeline/ap.py task-start T0001 \
55
+ --owned-path src [--isolated] [--review-required]
56
+ # Work in the path printed by task-start.
57
+ python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
58
+ # Isolated tasks only:
59
+ python3 docs/tools/autopipeline/ap.py task-integrate T0001
97
60
  ```
98
61
 
99
- `task-start` records the base revision, target branch, task branch, worktree,
100
- owned paths, prerequisite task SHAs, and writer lease in the repository manifest.
101
- Pass one `--owned-path` per owned path and one `--depends-on TASK_ID=SHA` per
102
- prerequisite. The writer defaults to `CODEX_THREAD_ID`; pass `--writer` only when
103
- an explicit stable identity is needed. Use `task-handoff` for an intentional
104
- lease transfer; its generation check prevents a stale writer from reclaiming the
105
- task. `commit-push` is valid only for the active writer inside the registered
106
- worktree and may stage only owned paths. If unknown changes appear, stop and
107
- report them. Never restore, reset, stash, clean, or otherwise modify another
108
- task's or the user's changes.
109
-
110
- After a reviewer returns, the main agent records the verdict and exact 64-character
111
- diff fingerprint with `task-review`. Any content change invalidates that review.
112
- `commit-push` and `task-integrate` require a current approval for the current
113
- fingerprint and verify prerequisite SHAs. If integration enters a rebase conflict,
114
- resolve it in the registered worktree, continue or abort the rebase as instructed,
115
- then run `task-resume`; do not bypass the conflicted manifest state.
116
-
117
- Treat `commit-push` plus `task-integrate` as one push stage. Run the fast gate
118
- only in `commit-push`; integration fetches/rebases, safely pushes the target, and
119
- cleans the task without repeating the gate. Successful target push ends the
120
- coding task. Do not wait for or inspect Jenkins/build/deploy results afterward.
121
- The task commit runs project commit hooks once. The internal backup task-branch
122
- push skips the pre-push hook; the final target-branch push runs it once.
123
- Integration creates no second evidence commit.
124
-
125
- After a successful integration, remove the clean worktree and merged local task
126
- branch. Delete the merged remote task branch by default. Use `task-finish` to
127
- retry cleanup for one integrated task and `task-prune` to clean registered merged
128
- tasks in bulk. Refuse cleanup when a worktree is dirty or a branch is unmerged.
129
- Do not update the primary checkout during integration; pull it explicitly when
130
- its user-owned state is ready. Treat unknown ignored files as user data and
131
- block cleanup; allow only explicitly disposable cache/build paths. Before a
132
- forced task-worktree removal, recursively require every initialized submodule
133
- to be clean and contain no unknown ignored data, local-only history, or
134
- unmirrored local branch. Block cleanup when the submodule has another linked
135
- worktree or its remotes cannot be refreshed. Before the validated forced removal,
136
- persist its refs and reflog commits in the Git common directory's managed
137
- submodule-recovery store so a remote race cannot erase the final copy. Never run
138
- submodule deinit from a linked task worktree because its shared config can alter
139
- the primary checkout.
140
-
141
- `task-start` enables Git worktree-scoped config and seeds task-local submodule
142
- URLs. After editing `.gitmodules`, run `task-submodule-sync` before submodule
143
- initialization or sync. Resolve relative URLs with Git's current-worktree
144
- default-remote semantics, not the integration remote. If shared/common submodule
145
- config differs from the task-start snapshot, stop and report it without restoring
146
- or overwriting the value. Treat residual module Git directories from a manual
147
- deinit/removal as user data: block forced cleanup until they are reinitialized or
148
- explicitly recovered.
149
-
150
- ## Development closure
151
-
152
- 1. The main agent analyzes and decomposes the request into bounded units with
153
- explicit dependencies, acceptance criteria, and owned paths.
154
- 2. Run justified `explorer`, `docs_researcher`, and `browser_debugger` discovery
155
- in parallel, then let the main agent merge their evidence into one design.
156
- 3. Create DD/ADR only for cross-module, API, DB, deployment/CI, security, key UI
157
- flow, or lasting structural decisions.
158
- 4. For one serial writer, inspect the current checkout first and work directly on
159
- its current branch when it is clean. Create registered task branches/worktrees
160
- only when the checkout already has changes or multiple writers run in parallel.
161
- Never share one worktree between writers; parallelize only dependency-free
162
- units with non-overlapping paths.
163
- 5. Review each stable diff with a read-only reviewer. Route blocking findings to
164
- the owning fixer and re-review after any change. The main agent records the
165
- current verdict with `task-review`, then hands the writer lease back before Git
166
- closure when required.
167
- 6. After all agents have returned, the main agent executes the changed-scope fast
168
- gate once, records `DEV-CLOSED`, commits, and pushes. Use `commit-push` for
169
- registered isolated tasks; on a clean serial current branch, commit and push
170
- that branch directly without creating a temporary branch.
171
- If that configured fast gate fails only because a dependency already present
172
- in the lockfile is not installed locally, restore the locked dependencies and
173
- rerun that same fast gate once. Missing dependencies in an accidentally or
174
- explicitly invoked standard/full diagnostic do not justify dependency
175
- installation or a full-gate rerun.
176
- 7. For isolated tasks, the main agent runs `task-integrate` in dependency order
177
- and cleans every task worktree and merged task branch. Direct serial work has
178
- no temporary branch to clean.
179
- 8. Stop. Jenkins owns later build/deploy work and the project owner owns actual
180
- acceptance. Ignore later external failures unless the user opens a diagnostic task.
181
-
182
- ## Structure policy
183
-
184
- Follow repository-native architecture first. Generic file-size, function-size,
185
- and regex import rules are advisory unless the project explicitly sets
186
- `structure.enforcement: blocking`. Search for reusable utilities, components,
187
- clients, validation, permissions, caching, retry, and automation before adding
188
- new helpers. Do not split files only to reduce line count.
189
-
190
- For repository-wide structural reviews, generate and read the health baseline
191
- and optimization backlog. Accepted debt is not a fresh blocker unless it worsens.
62
+ Direct `commit-push` runs the final gate and pushes the current target branch.
63
+ If the task has no diff, it clears its machine state without commit or push.
64
+ Isolated `commit-push` pushes the task branch; `task-integrate` serializes the
65
+ target push and removes clean merged temporary worktrees and branches. Use
66
+ `task-finish` or `task-prune` only for safe lifecycle cleanup.
67
+
68
+ ## Scale design and review by risk
69
+
70
+ Use `micro`, `standard`, and `high-risk` only to scale reasoning and guardrails;
71
+ never use them to trigger a full local repository gate automatically.
72
+
73
+ - Keep ordinary micro/standard work main-agent-only unless delegation has a
74
+ concrete latency or expertise benefit.
75
+ - Create DD/ADR only for lasting cross-module, API, data, security, deployment,
76
+ or key user-flow decisions.
77
+ - Require independent fingerprinted review for high-risk, cross-module,
78
+ explicitly configured, or parallel integration work.
79
+ - Route blocking review findings back to the owning writer and invalidate the
80
+ approval after any content change or rebase.
81
+ - Keep review inside the promised task scope. Adjacent pre-existing findings are
82
+ non-blocking follow-ups. Semantic changes require full review against a new
83
+ fingerprint; mechanical docs-only corrections may use a targeted recheck.
84
+
85
+ Historical debt does not block normal delivery. Block only new or worsened P0/P1
86
+ issues. Handle repository-wide governance through an explicit task and optional
87
+ baseline/backlog.
88
+
89
+ ## Use subagents when they improve throughput
90
+
91
+ Let the main agent own decomposition, architecture, dependencies, final gate,
92
+ Git closure, integration, and cleanup.
93
+
94
+ - Run independent read-only explorer, docs, or browser questions in parallel only
95
+ when the model judges their expected value higher than coordination cost;
96
+ classification may suggest capabilities but never auto-dispatches them.
97
+ - Dispatch fixers only for bounded, dependency-free units with non-overlapping
98
+ paths; give each parallel fixer its own task ID, writer lease, and registered
99
+ worktree. `task-start` creates exactly one writer/worktree.
100
+ - Start dependent writers only after prerequisite commits are integrated.
101
+ - Add a reviewer only when the risk policy requires one.
102
+ - Do not force fan-out for small serial tasks.
103
+
104
+ Subagents do not commit, push, integrate, clean branches, or run the final project
105
+ gate. Use the bundled orchestration contract when structured assignments/results
106
+ are useful; ordinary main-agent work needs no task ledger.
107
+
108
+ ## Run real changed-scope validation
109
+
110
+ Keep classification under `risk.rules` and executable checks under
111
+ `validation.routes`. Match every changed path against all routes, collect command
112
+ references in configuration order, remove duplicates, and run each once.
192
113
 
193
114
  ```bash
194
- python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
115
+ python3 docs/tools/autopipeline/ap.py validation-map-check --path <PATH>
116
+ python3 docs/tools/autopipeline/ap.py light-gate --scope changed --explain
195
117
  ```
196
118
 
197
- ## Collaboration roles
198
-
199
- Role templates provide behavior and permission boundaries, while the active
200
- client supplies the available model unless a project keeps an explicit override.
201
- `classify` returns both justified roles and a structured `agent_plan`:
202
-
203
- - `explorer`: read-only repository discovery and root-cause tracing.
204
- - `docs_researcher`: current official API/version research.
205
- - `browser_debugger`: UI reproduction and browser evidence.
206
- - `fixer`: bounded implementation after scope is clear.
207
- - `reviewer`: correctness, security, regression, and evidence review.
208
-
209
- For standard and high-risk write tasks, use the following fan-out/fan-in contract:
210
-
211
- 1. The main agent owns decomposition and supplies every subagent with `task_id`,
212
- role, scope, dependencies, acceptance criteria, and expected output.
213
- 2. Discovery roles are read-only and may run in parallel. Browser work is limited
214
- to requested reproduction/evidence; it does not replace owner acceptance.
215
- 3. Each fixer receives `execution_mode` and owned paths. Direct mode also names
216
- the clean current checkout; isolated mode supplies a task branch and absolute
217
- worktree path. It may edit only its assigned checkout and must not commit,
218
- push, integrate, clean, or run the project gate.
219
- 4. Each reviewer receives a stable diff and binds approved or changes-requested
220
- to its fingerprint. Changes go back to the same fixer and invalidate approval.
221
- 5. Every subagent returns exactly one JSON object conforming to
222
- `data/contracts/orchestration-v1.schema.json#/$defs/agentResult`, with integer
223
- `contract_version: 1`. It includes node/task/role, base SHA, dependencies,
224
- owned and changed paths, diff fingerprint, evidence, findings, verdict, risks,
225
- and next owner. Read-only roles return no changed paths.
226
- 6. The main agent alone owns architecture decisions, the single fast gate per
227
- write task, closure records, commits, integration, push, and branch cleanup.
228
-
229
- Micro tasks stay main-agent-only unless they contain genuinely independent work
230
- whose benefit exceeds delegation overhead. If subagents are unavailable, the
231
- main agent executes the same stages sequentially without weakening isolation.
232
-
233
- ## Tool routing
234
-
235
- - Local code, tests, gates, and Git: shell, repository scripts, and `ap.py`.
236
- - Current library/API behavior: official documentation MCP or matching skill.
237
- - UI: in-app browser for local pages, Chrome for existing logged-in state,
238
- Playwright for deterministic automation, Computer Use for unsupported native UI.
239
- - PR/issue state: GitHub connector; local Git for local changes and pushes.
240
- - Design, security, analytics, and document artifacts: use the matching installed
241
- skill or connector before manual recreation.
242
- - Credentials: use the direct values configured under `access.*` in
243
- `docs/ENGINEERING.md`; do not invent or echo values unnecessarily.
244
-
245
- ## Optional documents and operations
119
+ - Fail before staging when changed code is unmapped or a route references a
120
+ missing/blank command.
121
+ - Allow docs-only changes to use the built-in diff check.
122
+ - Treat `git diff --check` as additional hygiene, never as business validation.
123
+ - Allow focused tests and test/fix/retest loops during development.
124
+ - Run one final routed closure gate after the diff is stable.
125
+ - Do not automatically run full regression, Docker, builds, Jenkins, deployment,
126
+ API verification, or target checks.
127
+ - Do not install dependencies proactively. Only after the selected final route
128
+ fails because a repository-locked dependency is absent may it be restored once;
129
+ then retry only that affected route.
130
+
131
+ ## Keep project state small
132
+
133
+ Store task manifests, the installed Skill version, ownership, leases,
134
+ dependencies, and review fingerprints in the Git common directory. Store gate
135
+ timing/evidence under `.local` by default.
136
+ Do not create taskbook, closure Markdown, evidence JSONL, active-task, or design
137
+ documents for ordinary work. Preserve existing project documents as user data;
138
+ create or update them only when explicitly useful.
139
+
140
+ Keep root `AGENTS.md` byte-identical to the packaged canonical file; sync replaces
141
+ it as a whole and archives its previous contents as historical, non-authoritative
142
+ context. Keep `docs/ENGINEERING.md` as the only manual workflow configuration
143
+ source. Put larger product, repository, and runtime facts in `docs/project/`, not
144
+ in root AGENTS or duplicated workflow sections. Allow direct plaintext values
145
+ under `access.*`; do not invent or echo credentials.
146
+
147
+ Pure ledger, closure, or archive reconciliation is a terminal maintenance action:
148
+ run its targeted consistency check and commit once. It must not create another
149
+ active task, closure record, evidence chain, or review cycle for closing itself.
150
+
151
+ ## Install and upgrade
246
152
 
247
153
  ```bash
248
- python3 docs/tools/autopipeline/ap.py scaffold all --write
249
- python3 docs/tools/autopipeline/ap.py docs-ledger-check
250
- python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
251
- python3 docs/tools/autopipeline/ap.py gate-profile
252
- python3 docs/tools/autopipeline/ap.py task-start <TASK_ID> --owned-path <PATH> [--depends-on <TASK_ID=SHA>] [--writer <WRITER>]
253
- python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
254
- python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
255
- python3 docs/tools/autopipeline/ap.py task-review <TASK_ID> --verdict <VERDICT> --diff-fingerprint <SHA256> [--reviewer <REVIEWER>]
256
- python3 docs/tools/autopipeline/ap.py task-handoff <TASK_ID> --from <WRITER> --to <WRITER> [--generation <N>]
257
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>" [--writer <WRITER>]
258
- python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
259
- python3 docs/tools/autopipeline/ap.py task-resume <TASK_ID>
260
- python3 docs/tools/autopipeline/ap.py task-finish <TASK_ID>
261
- python3 docs/tools/autopipeline/ap.py task-prune
154
+ autocoding init
155
+ autocoding sync --projects .
156
+ python3 docs/tools/autopipeline/ap.py upgrade --dry-run
157
+ python3 docs/tools/autopipeline/ap.py upgrade --write
158
+ python3 docs/tools/autopipeline/ap.py doctor
262
159
  ```
263
160
 
264
- `status` and `sync` manage only the minimal required scaffold. Existing optional
265
- documents and legacy tool copies are preserved but do not count as drift.
161
+ Finish every registered task before syncing a different runtime version. Upgrade
162
+ must preserve project configuration, access values, custom role agents, optional
163
+ documents, and explicit model overrides while removing obsolete managed Skill
164
+ files and filling new managed assets. Root `AGENTS.md` is the exception: it is
165
+ fully replaced by the canonical version, with the previous file archived under
166
+ `docs/archive/workflow/`.