@elvis1513/auto-coding-skill 4.0.0 → 4.1.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 +61 -14
- package/cli/assets/agents/reviewer.toml +3 -2
- package/cli/assets/skill/SKILL.md +38 -92
- package/cli/assets/skill/data/contracts/orchestration-v1.schema.json +16 -1
- package/cli/assets/skill/data/policies/workflow-migrations-v1.json +291 -5
- package/cli/assets/skill/data/templates/ENGINEERING.md +40 -134
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +117 -27
- package/cli/assets/skill/scripts/__pycache__/core.cpython-314.pyc +0 -0
- package/cli/assets/skill/scripts/__pycache__/scaffold_templates.cpython-314.pyc +0 -0
- package/cli/assets/skill/scripts/ap.py +427 -57
- package/cli/assets/skill/scripts/core.py +21 -5
- package/cli/assets/skill/scripts/scaffold_templates.py +40 -5
- package/cli/src/index.js +192 -85
- package/cli/tests/ap_concurrency_test.py +77 -11
- package/cli/tests/ap_profiles_test.py +66 -23
- package/cli/tests/index.test.js +98 -66
- package/package.json +1 -1
- package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +0 -17
- package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +0 -30
package/README.md
CHANGED
|
@@ -5,7 +5,12 @@ A delivery-first Codex engineering workflow:
|
|
|
5
5
|
`analysis → decomposition → necessary design → development → one final fast
|
|
6
6
|
changed-scope gate → commit/push`.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The Skill is a selectable guardrail, not a command sequence that must run for
|
|
9
|
+
every task. The model skips machinery whose expected benefit does not exceed its
|
|
10
|
+
cost; read-only work and obvious small clean-checkout changes normally stay direct.
|
|
11
|
+
|
|
12
|
+
Version 4.1.1 consolidates the 4.x delivery-first workflow into one canonical
|
|
13
|
+
repository contract. Version 4.0 replaced the 3.x governance-first defaults with progressive
|
|
9
14
|
guardrails. Clean single-writer work stays on the current branch. Worktrees,
|
|
10
15
|
parallel fixers, fingerprint review, durable design records, and stronger
|
|
11
16
|
affected-scope checks are enabled only when concurrency or risk justifies them.
|
|
@@ -26,7 +31,7 @@ The project install contains:
|
|
|
26
31
|
.agents/agents/
|
|
27
32
|
docs/ENGINEERING.md
|
|
28
33
|
docs/tools/autopipeline/ap.py
|
|
29
|
-
AGENTS.md (managed
|
|
34
|
+
AGENTS.md (fully managed canonical repository contract)
|
|
30
35
|
```
|
|
31
36
|
|
|
32
37
|
Ordinary projects no longer receive taskbook or closure logs. Existing optional
|
|
@@ -60,9 +65,13 @@ The result includes:
|
|
|
60
65
|
- `execution_mode=isolated`: dirty checkout, explicit isolation, or multiple writers.
|
|
61
66
|
- `execution_mode=none`: no task signal or change; create no branch/worktree.
|
|
62
67
|
- `review_required` and `design_required`: risk-based escalation decisions.
|
|
68
|
+
- `mechanism_plan.required`: the complete minimum mechanism set for the task.
|
|
69
|
+
- `mechanism_plan.not_required`: mechanisms that stay off unless the user asks.
|
|
63
70
|
- an adaptive agent plan that does not force fan-out for ordinary work.
|
|
64
71
|
|
|
65
|
-
|
|
72
|
+
Clean serial work proceeds directly on the current branch with normal Git; it does
|
|
73
|
+
not create machine lifecycle state. Use `task-start` only when classification
|
|
74
|
+
requires isolation/review or the user explicitly requests lifecycle tracking:
|
|
66
75
|
|
|
67
76
|
```bash
|
|
68
77
|
python3 docs/tools/autopipeline/ap.py task-start T0001 \
|
|
@@ -71,16 +80,15 @@ python3 docs/tools/autopipeline/ap.py commit-push T0001 \
|
|
|
71
80
|
--msg "T0001: fix order retry"
|
|
72
81
|
```
|
|
73
82
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
If no diff was produced, it clears the manifest without commit or push.
|
|
83
|
+
When a required review still uses the current clean checkout, `task-start` records
|
|
84
|
+
a direct manifest without creating a branch/worktree. If no diff is produced,
|
|
85
|
+
closure clears the manifest without commit or push.
|
|
78
86
|
|
|
79
87
|
Dirty or parallel work receives an isolated task branch/worktree:
|
|
80
88
|
|
|
81
89
|
```bash
|
|
82
90
|
python3 docs/tools/autopipeline/ap.py task-start T0002 \
|
|
83
|
-
--owned-path backend --
|
|
91
|
+
--owned-path backend --review-required
|
|
84
92
|
# implement in the printed worktree
|
|
85
93
|
python3 docs/tools/autopipeline/ap.py task-review T0002 \
|
|
86
94
|
--verdict approved --diff-fingerprint "$SHA256"
|
|
@@ -93,6 +101,10 @@ Integration serializes the target push and removes clean merged worktrees and
|
|
|
93
101
|
temporary branches. Unknown changes, unmerged history, unsafe ignored data, or
|
|
94
102
|
dirty submodules block cleanup rather than being discarded.
|
|
95
103
|
|
|
104
|
+
Parallel development uses one task ID and one `task-start` per writer. `--writers`
|
|
105
|
+
belongs to `classify` planning only; the runtime rejects overlapping active
|
|
106
|
+
`owned_paths` and never creates multiple writers in one task/worktree.
|
|
107
|
+
|
|
96
108
|
## Real changed-scope validation
|
|
97
109
|
|
|
98
110
|
Risk classification and validation execution are deliberately separate:
|
|
@@ -104,6 +116,8 @@ commands:
|
|
|
104
116
|
|
|
105
117
|
validation:
|
|
106
118
|
on_unmapped: error
|
|
119
|
+
max_command_seconds: 120
|
|
120
|
+
max_total_seconds: 180
|
|
107
121
|
routes:
|
|
108
122
|
- name: backend
|
|
109
123
|
paths: ["backend/**", "contracts/**"]
|
|
@@ -138,6 +152,10 @@ closure gate is limited to one stable-diff run. Full regression, Docker, builds,
|
|
|
138
152
|
Jenkins, deployment, API verification, and target checks remain explicit
|
|
139
153
|
diagnostics outside normal closure.
|
|
140
154
|
|
|
155
|
+
The final closure gate is hard-bounded to at most 120 seconds per command and 180
|
|
156
|
+
seconds total; projects may lower those values. A timeout requires a narrower
|
|
157
|
+
route and never triggers a broader fallback.
|
|
158
|
+
|
|
141
159
|
## Risk and subagent policy
|
|
142
160
|
|
|
143
161
|
- Micro and standard work default to the main agent.
|
|
@@ -152,13 +170,14 @@ diagnostics outside normal closure.
|
|
|
152
170
|
|
|
153
171
|
The main agent owns architecture, final validation, Git closure, ordered
|
|
154
172
|
integration, push, and cleanup. Push ends the coding task; later CI/acceptance is
|
|
155
|
-
|
|
173
|
+
not polled automatically. An explicitly requested failure diagnosis may continue
|
|
174
|
+
in the same conversation/task without an artificial second ledger lifecycle.
|
|
156
175
|
|
|
157
176
|
## Upgrade and multi-project sync
|
|
158
177
|
|
|
159
|
-
Finish
|
|
160
|
-
|
|
161
|
-
|
|
178
|
+
Finish every registered task using its currently installed runtime before syncing
|
|
179
|
+
a different Skill version. Batch sync fails before any writes when it finds an
|
|
180
|
+
active manifest, regardless of schema version.
|
|
162
181
|
|
|
163
182
|
```bash
|
|
164
183
|
autocoding status --projects /path/a,/path/b
|
|
@@ -168,8 +187,36 @@ autocoding sync --projects /path/a,/path/b
|
|
|
168
187
|
|
|
169
188
|
Sync replaces the managed Skill directory, so missing files are restored and
|
|
170
189
|
obsolete managed files are removed. It preserves project frontmatter, access
|
|
171
|
-
values, custom agents, explicit model overrides, optional documents, and
|
|
172
|
-
outside managed
|
|
190
|
+
values, custom role agents, explicit model overrides, optional documents, and
|
|
191
|
+
project-specific facts outside the managed ENGINEERING block. Root `AGENTS.md` is
|
|
192
|
+
replaced as a whole; its previous content is archived under
|
|
193
|
+
`docs/archive/workflow/` as historical, non-authoritative context.
|
|
194
|
+
|
|
195
|
+
## What changed in 4.1.1
|
|
196
|
+
|
|
197
|
+
- Added a machine-readable minimum mechanism plan and rejected unnecessary clean
|
|
198
|
+
serial task lifecycles unless explicitly requested.
|
|
199
|
+
- Added hard per-command and total time ceilings for the final changed-scope gate.
|
|
200
|
+
- Made root `AGENTS.md` the sole behavioral protocol, reduced `SKILL.md` to
|
|
201
|
+
invocation guidance, and reduced `ENGINEERING.md` to project configuration and
|
|
202
|
+
facts.
|
|
203
|
+
|
|
204
|
+
## What changed in 4.1.0
|
|
205
|
+
|
|
206
|
+
- Made root `AGENTS.md` byte-identical across installed projects and whole-file
|
|
207
|
+
managed on every full sync/upgrade.
|
|
208
|
+
- Established code/tests/runtime as the source of current behavior and
|
|
209
|
+
`ENGINEERING.md` as the single project workflow/configuration source.
|
|
210
|
+
- Added an engineering-centered documentation framework plus optional
|
|
211
|
+
`docs/project/` fact templates.
|
|
212
|
+
- Prevented Skill upgrades while any registered task is active and recorded the
|
|
213
|
+
installed Skill version in new task manifests.
|
|
214
|
+
- Made reviewer scope bounded, with targeted recheck for mechanical docs-only
|
|
215
|
+
fixes and non-blocking handling of adjacent findings.
|
|
216
|
+
- Defined ledger/archive reconciliation as a terminal maintenance action, so
|
|
217
|
+
closing records cannot recursively create more task records.
|
|
218
|
+
- Kept explicit Jenkins failure diagnosis in the same requested task while
|
|
219
|
+
preserving push-as-completion and no automatic polling.
|
|
173
220
|
|
|
174
221
|
## What changed in 4.0.0
|
|
175
222
|
|
|
@@ -20,8 +20,9 @@ developer_instructions = """
|
|
|
20
20
|
- 复现条件
|
|
21
21
|
- 建议修法
|
|
22
22
|
9. 发现测试不足时,指出应补哪些测试或验证路径。
|
|
23
|
-
10. 结论必须是 approved 或 changes-requested;changes-requested 只返回 owning_fixer
|
|
23
|
+
10. 结论必须是 approved 或 changes-requested;changes-requested 只返回 owning_fixer,修改后必须绑定新的 diff fingerprint。代码、配置或行为语义变化需要重新审查;仅链接、归档索引、状态措辞等机械文档修正,可由同一 reviewer 只做 targeted recheck,不必重跑完整审计。
|
|
24
24
|
11. 不修改代码,不提交、不推送、不集成、不清理分支;审查不扩展本地门禁。
|
|
25
25
|
12. 最终只返回一个 JSON 对象,不要 Markdown 或代码围栏。对象必须符合 `.agents/skills/auto-coding-skill/data/contracts/orchestration-v1.schema.json#/$defs/agentResult`,包含全部必填字段,`contract_version` 固定为 1,`role` 固定为 `reviewer`,`changed_paths` 固定为空数组,`diff_fingerprint` 必须原样返回;审查完成时 `status=completed` 且 `verdict` 只能是 `approved` 或 `changes-requested`,无法继续时使用 `status=blocked`、`verdict=blocked`。findings 按 P0/P1/P2/P3 排序。
|
|
26
|
-
13.
|
|
26
|
+
13. 只阻断当前任务承诺范围内由本次变更新增或恶化的问题。相邻或既有问题写入 risks/follow-up,不得无限扩大当前任务和 review 范围。
|
|
27
|
+
14. 目标分支推送成功后,不自动跟踪 Jenkins、部署或项目负责人的实际验收;用户明确要求诊断本次推送引发的失败时,可在同一会话和任务范围继续,不要求人为新建台账任务。
|
|
27
28
|
"""
|
|
@@ -1,127 +1,74 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: auto-coding-skill
|
|
3
|
-
description: Delivery-first engineering workflow for repository changes. Use for analysis, task decomposition, necessary design, implementation,
|
|
3
|
+
description: Delivery-first engineering workflow for repository changes. Use for analysis, task decomposition, necessary design, implementation, bounded changed-scope validation, safe commit/push, adaptive Git isolation, parallel writer coordination, and temporary branch cleanup. Keep clean serial work on the current branch and add lifecycle, worktrees, subagents, design, or review only when classify marks them required or the user explicitly requests them.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Auto Coding Skill
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
## Use the two authorities
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
validation routes. Treat target-branch push as coding completion. Do not poll or
|
|
15
|
-
fix Jenkins, deployment, or owner acceptance unless the user opens a separate
|
|
16
|
-
diagnostic task.
|
|
10
|
+
Read root `AGENTS.md` for the shared behavioral protocol. Read
|
|
11
|
+
`docs/ENGINEERING.md` frontmatter for project facts, access values, risk rules,
|
|
12
|
+
validation routes, and time budgets. Do not reconstruct or duplicate those rules
|
|
13
|
+
from historical task documents.
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
Normal delivery is:
|
|
19
16
|
|
|
20
|
-
|
|
17
|
+
`analysis → decomposition → necessary design → development → one bounded final
|
|
18
|
+
changed-scope gate → commit/push`.
|
|
21
19
|
|
|
22
|
-
|
|
23
|
-
- Use an isolated task branch/worktree when unrelated changes already exist,
|
|
24
|
-
when more than one writer will run, or when the project explicitly requires it.
|
|
25
|
-
- Use one writer per worktree and non-overlapping owned paths.
|
|
26
|
-
- Create no temporary branch merely to analyze a task or when no diff is produced.
|
|
27
|
-
- Never restore, reset, stash, clean, or modify unknown user/task changes.
|
|
20
|
+
## Select the minimum mechanism set
|
|
28
21
|
|
|
29
|
-
|
|
22
|
+
Skip classification for read-only work, obvious clean serial edits, and terminal
|
|
23
|
+
ledger maintenance. When impact, risk, or concurrency is unclear, run:
|
|
30
24
|
|
|
31
25
|
```bash
|
|
32
26
|
python3 docs/tools/autopipeline/ap.py classify --scope auto \
|
|
33
27
|
--planned-path <PATH> --intent "<intent>" [--writers <N>]
|
|
34
28
|
```
|
|
35
29
|
|
|
36
|
-
`
|
|
37
|
-
`
|
|
38
|
-
|
|
30
|
+
Follow `mechanism_plan.required`. Do not add anything listed under
|
|
31
|
+
`mechanism_plan.not_required` unless the user explicitly requests it. In
|
|
32
|
+
particular, ordinary direct work does not create a task lifecycle.
|
|
39
33
|
|
|
40
|
-
Use the
|
|
34
|
+
Use the registered lifecycle only when classification requires isolation or
|
|
35
|
+
fingerprinted review, or when the user explicitly requests it:
|
|
41
36
|
|
|
42
37
|
```bash
|
|
43
38
|
python3 docs/tools/autopipeline/ap.py task-start T0001 \
|
|
44
|
-
--owned-path src [--
|
|
45
|
-
# Work in the path printed by task-start.
|
|
39
|
+
--owned-path src [--isolated] [--review-required]
|
|
46
40
|
python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
|
|
47
41
|
# Isolated tasks only:
|
|
48
42
|
python3 docs/tools/autopipeline/ap.py task-integrate T0001
|
|
49
43
|
```
|
|
50
44
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
target push and removes clean merged temporary worktrees and branches. Use
|
|
55
|
-
`task-finish` or `task-prune` only for safe lifecycle cleanup.
|
|
56
|
-
|
|
57
|
-
## Scale design and review by risk
|
|
58
|
-
|
|
59
|
-
Use `micro`, `standard`, and `high-risk` only to scale reasoning and guardrails;
|
|
60
|
-
never use them to trigger a full local repository gate automatically.
|
|
61
|
-
|
|
62
|
-
- Keep ordinary micro/standard work main-agent-only unless delegation has a
|
|
63
|
-
concrete latency or expertise benefit.
|
|
64
|
-
- Create DD/ADR only for lasting cross-module, API, data, security, deployment,
|
|
65
|
-
or key user-flow decisions.
|
|
66
|
-
- Require independent fingerprinted review for high-risk, cross-module,
|
|
67
|
-
explicitly configured, or parallel integration work.
|
|
68
|
-
- Route blocking review findings back to the owning writer and invalidate the
|
|
69
|
-
approval after any content change or rebase.
|
|
70
|
-
|
|
71
|
-
Historical debt does not block normal delivery. Block only new or worsened P0/P1
|
|
72
|
-
issues. Handle repository-wide governance through an explicit task and optional
|
|
73
|
-
baseline/backlog.
|
|
45
|
+
Each parallel writer uses a distinct task ID, registered worktree, writer lease,
|
|
46
|
+
dependency SHAs, and non-overlapping `owned_paths`. The main agent alone runs the
|
|
47
|
+
final gate, integrates, pushes, and cleans safely merged temporary branches.
|
|
74
48
|
|
|
75
|
-
##
|
|
76
|
-
|
|
77
|
-
Let the main agent own decomposition, architecture, dependencies, final gate,
|
|
78
|
-
Git closure, integration, and cleanup.
|
|
79
|
-
|
|
80
|
-
- Run independent read-only explorer, docs, or browser questions in parallel.
|
|
81
|
-
- Dispatch fixers only for bounded, dependency-free units with non-overlapping
|
|
82
|
-
paths; give each parallel fixer its own registered worktree.
|
|
83
|
-
- Start dependent writers only after prerequisite commits are integrated.
|
|
84
|
-
- Add a reviewer only when the risk policy requires one.
|
|
85
|
-
- Do not force fan-out for small serial tasks.
|
|
86
|
-
|
|
87
|
-
Subagents do not commit, push, integrate, clean branches, or run the final project
|
|
88
|
-
gate. Use the bundled orchestration contract when structured assignments/results
|
|
89
|
-
are useful; ordinary main-agent work needs no task ledger.
|
|
90
|
-
|
|
91
|
-
## Run real changed-scope validation
|
|
92
|
-
|
|
93
|
-
Keep classification under `risk.rules` and executable checks under
|
|
94
|
-
`validation.routes`. Match every changed path against all routes, collect command
|
|
95
|
-
references in configuration order, remove duplicates, and run each once.
|
|
49
|
+
## Close with the bounded routed gate
|
|
96
50
|
|
|
97
51
|
```bash
|
|
98
52
|
python3 docs/tools/autopipeline/ap.py validation-map-check --path <PATH>
|
|
99
53
|
python3 docs/tools/autopipeline/ap.py light-gate --scope changed --explain
|
|
100
54
|
```
|
|
101
55
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
- Allow focused tests and test/fix/retest loops during development.
|
|
107
|
-
- Run one final routed closure gate after the diff is stable.
|
|
108
|
-
- Do not automatically run full regression, Docker, builds, Jenkins, deployment,
|
|
109
|
-
API verification, or target checks.
|
|
110
|
-
- Do not automatically install dependencies. If the final route needs a locked
|
|
111
|
-
dependency absent from the checkout, restore it once and retry only that route.
|
|
112
|
-
|
|
113
|
-
## Keep project state small
|
|
56
|
+
Every changed code/config path must map to a real project command. The runtime
|
|
57
|
+
de-duplicates matched commands and enforces both per-command and total closure
|
|
58
|
+
budgets. A timeout means the route must be narrowed; it never falls back to a full
|
|
59
|
+
build. Focused test/fix/retest loops remain allowed before the final gate.
|
|
114
60
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
create or update them only when explicitly useful.
|
|
61
|
+
Run full regression, Docker, Jenkins, deployment, browser/device writes, or target
|
|
62
|
+
acceptance only as an explicit diagnostic. If the user asks to diagnose the
|
|
63
|
+
just-pushed failure, continue in the same conversation/task without inventing a
|
|
64
|
+
new ledger lifecycle.
|
|
120
65
|
|
|
121
|
-
Keep
|
|
122
|
-
Allow direct plaintext values under `access.*`; do not invent or echo credentials.
|
|
66
|
+
## Keep state and upgrades safe
|
|
123
67
|
|
|
124
|
-
|
|
68
|
+
Machine task state, leases, fingerprints, and gate evidence stay in Git
|
|
69
|
+
common/local state. Ordinary work creates no taskbook, closure Markdown, evidence
|
|
70
|
+
JSONL, active-task, or design artifact. Terminal ledger reconciliation validates
|
|
71
|
+
and commits once without creating another lifecycle.
|
|
125
72
|
|
|
126
73
|
```bash
|
|
127
74
|
autocoding init
|
|
@@ -131,7 +78,6 @@ python3 docs/tools/autopipeline/ap.py upgrade --write
|
|
|
131
78
|
python3 docs/tools/autopipeline/ap.py doctor
|
|
132
79
|
```
|
|
133
80
|
|
|
134
|
-
Finish
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
files and filling new managed assets.
|
|
81
|
+
Finish registered tasks before changing runtime versions. Sync replaces the
|
|
82
|
+
canonical root `AGENTS.md`, archives its previous content, preserves project facts
|
|
83
|
+
and access values, and converges all managed Skill/runtime/agent assets together.
|
|
@@ -11,6 +11,17 @@
|
|
|
11
11
|
"type": "string"
|
|
12
12
|
}
|
|
13
13
|
},
|
|
14
|
+
"mechanismPlan": {
|
|
15
|
+
"type": "object",
|
|
16
|
+
"required": ["required", "not_required", "lifecycle_required", "rule"],
|
|
17
|
+
"properties": {
|
|
18
|
+
"required": { "$ref": "#/$defs/stringArray" },
|
|
19
|
+
"not_required": { "$ref": "#/$defs/stringArray" },
|
|
20
|
+
"lifecycle_required": { "type": "boolean" },
|
|
21
|
+
"rule": { "type": "string", "minLength": 1 }
|
|
22
|
+
},
|
|
23
|
+
"additionalProperties": false
|
|
24
|
+
},
|
|
14
25
|
"fingerprint": {
|
|
15
26
|
"type": "string",
|
|
16
27
|
"pattern": "^$|^[0-9a-f]{64}$"
|
|
@@ -444,7 +455,8 @@
|
|
|
444
455
|
"profile",
|
|
445
456
|
"categories",
|
|
446
457
|
"recommended_agents",
|
|
447
|
-
"agent_plan"
|
|
458
|
+
"agent_plan",
|
|
459
|
+
"mechanism_plan"
|
|
448
460
|
],
|
|
449
461
|
"properties": {
|
|
450
462
|
"contract_version": {
|
|
@@ -483,6 +495,9 @@
|
|
|
483
495
|
},
|
|
484
496
|
"agent_plan": {
|
|
485
497
|
"$ref": "#/$defs/agentPlan"
|
|
498
|
+
},
|
|
499
|
+
"mechanism_plan": {
|
|
500
|
+
"$ref": "#/$defs/mechanismPlan"
|
|
486
501
|
}
|
|
487
502
|
},
|
|
488
503
|
"additionalProperties": true
|