@elvis1513/auto-coding-skill 2.1.0 → 2.1.2

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 CHANGED
@@ -2,12 +2,11 @@
2
2
 
3
3
  Engineering workflow skill for:
4
4
 
5
- - Claude Code
6
- - Codex CLI
5
+ - shared `.agents` skills and role templates
7
6
 
8
- This skill targets Go backend + frontend monorepo projects that rely on Jenkins for build and deployment. The default `dev` mode is optimized for fast development: light gate, early closure record, commit, push, then move to the next task. Switch to `verify` mode when Jenkins and target-environment evidence must be completed before closure.
7
+ This skill targets general software projects that need a disciplined task -> design -> implementation -> verification -> closure workflow. The default `dev` mode is optimized for fast development: light gate, early closure record, commit, push, then move to the next task. Switch to `verify` mode when configured CI/Jenkins and target-environment evidence must be completed before closure.
9
8
 
10
- `docs/ENGINEERING.md` is intentionally Git-tracked. The environment fields kept in that file are mandatory, must be filled with real values, and are committed as part of project maintenance. Unused environment items should be removed instead of being kept as placeholders.
9
+ `docs/ENGINEERING.md` is intentionally Git-tracked. Environment fields kept in that file are mandatory only when their verification surface is enabled. Unused environment items should be removed instead of being kept as placeholders.
11
10
 
12
11
  ## Install
13
12
 
@@ -23,6 +22,35 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
23
22
 
24
23
  ## Release Notes
25
24
 
25
+ ### v2.1.2
26
+
27
+ - Fixed `docs-ledger-archive` so settled task states such as `Superseded by ...`, `External Dependency`, `Deployed`, `Completed`, `Archived`, `Local PASS`, and `Local Verified` are recognized as archivable instead of blocking physical ledger cleanup.
28
+ - Added a package-safe regression test for those docs ledger archive states.
29
+
30
+ ### v2.1.1
31
+
32
+ - Removed client-specific init targets from the npm CLI; installs now target the shared `.agents` layout only.
33
+ - `ap.py install --bridges` now creates a generic `AGENTS.md` bridge instead of client-named bridge files.
34
+ - `autocoding init --force` now preserves custom files in `.agents/agents`; only managed template files are refreshed.
35
+ - `autocoding init --dest` now accepts a repo root, `.agents` directory, `.agents/skills`, or the direct `.agents/skills/auto-coding-skill` directory without nesting `.agents/.agents`.
36
+ - `autocoding sync` now creates a missing `docs/ENGINEERING.md` from the template, while still preserving existing project-specific config.
37
+ - `autocoding init` now preflights both skill and agent targets before writing files, preventing partial installs when one target already exists.
38
+ - Added CLI installer regression tests for dest variants, partial-init failure, sync convergence, bridge generation, custom-agent preservation, and managed bridge cleanup.
39
+ - Made `npm test` runnable from the published package by testing packaged assets separately from source-tree asset synchronization checks.
40
+ - `autocoding status/sync` now treats `.agents/agents` as a shared directory: managed templates are checked and refreshed, while project-specific custom agents are preserved.
41
+ - Added `install --force` protection: plain `ap.py install` now refuses to overwrite existing generated docs/tooling and directs existing projects to `upgrade`.
42
+ - Added generated-noise filtering for `__pycache__`, `.pyc`, and `.DS_Store` so `impact`, structure checks, and `commit-push` do not treat local Python cache files as real project changes.
43
+ - Added generic `--ci-build` / `--ci-failure` aliases for closure commands while keeping legacy Jenkins flags compatible.
44
+ - Added `ap.py docs-ledger-check` to prevent documentation ledgers from growing without a real archive.
45
+ - Added `ap.py docs-ledger-archive --plan|--write [--period 2026-06]` for generic physical archiving of closed taskbook entries, non-conflicting closure records, and matching top-level DD files.
46
+ - `doctor` now runs docs ledger health checks by default: large `taskbook.md`, `closure-log.md`, or active `docs/design/T*.md` sets require physical archives.
47
+ - `doctor` records a standalone `docs_ledger_check` evidence event with counts and blocking details.
48
+ - `docs-ledger-check` now fails on missing active ledger files instead of treating them as empty ledgers.
49
+ - `autocoding status` now parses `docs/ENGINEERING.md` frontmatter key paths instead of matching config tokens in prose.
50
+ - Added `verification.target_env_required` and `verification.jenkins_required` so non-Jenkins or local-only projects can keep `doctor` generic.
51
+ - Added `docs.task_archive_dir`, `docs.design_archive_dir`, `docs.archive_index`, and active ledger budget settings to `docs/ENGINEERING.md`.
52
+ - Clarified that `archive-index.md` is only navigation; it does not replace monthly or legacy physical archives.
53
+
26
54
  ### v2.1.0
27
55
 
28
56
  - Added project upgrade support: `ap.py upgrade --dry-run|--write` safely syncs tooling and merges missing `docs/ENGINEERING.md` keys without overwriting existing values.
@@ -61,16 +89,16 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
61
89
 
62
90
  ### v2.0.2
63
91
 
64
- - Added default Codex subagent templates under `.agents/agents`.
65
- - `autocoding init --ai codex` and `autocoding init --ai all` now install the Codex agent templates automatically.
66
- - Updated Codex agent defaults to current model names: `gpt-5.5`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`; highest reasoning uses `xhigh`.
92
+ - Added default subagent templates under `.agents/agents`.
93
+ - `autocoding init` installs the managed agent templates automatically.
94
+ - Updated agent defaults to current model names: `gpt-5.5`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`; highest reasoning uses `xhigh`.
67
95
  - Added concrete capability routing for MCP servers, installed skills, plugins/apps/connectors, browser tools, GitHub, Figma, security review, and artifact workflows.
68
96
  - Changed multi-agent guidance from unconditional delegation to a role model that works either as real subagents or as sequential main-agent phases.
69
97
  - Hardened CLI help/argument validation, asset sync checks, and stricter autopipeline config diagnostics.
70
98
 
71
99
  ### v2.0.1
72
100
 
73
- - Updated the Codex installer target to `.agents/skills`, matching current Codex global and project skill discovery.
101
+ - Updated the installer target to `.agents/skills`, matching current global and project skill discovery.
74
102
 
75
103
  ### v0.3.1
76
104
 
@@ -101,15 +129,15 @@ workflow:
101
129
 
102
130
  `verify` 完整闭环:
103
131
 
104
- `需求/任务记录 -> 最小设计 -> 开发 -> 本地轻量校验 -> commit/push -> Jenkins 构建部署验证 -> 目标环境验证 -> 写 PASS 闭环`
132
+ `需求/任务记录 -> 最小设计 -> 开发 -> 本地轻量校验 -> commit/push -> 已启用的 CI/Jenkins 验证 -> 已启用的目标环境验证 -> 写 PASS 闭环`
105
133
 
106
134
  具体执行顺序:
107
135
 
108
136
  1. 需求确认
109
- - 明确任务范围、影响服务、是否涉及 API / 数据库 / 部署 / Jenkins / 前端页面。
137
+ - 明确任务范围、影响服务、是否涉及 API / 数据库 / 部署 / CI/Jenkins / 前端页面。
110
138
  2. 最小设计记录
111
139
  - 普通小改动只更新 `taskbook` 或相关设计文档的一小段。
112
- - 跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD。
140
+ - 跨模块、接口、数据库、部署、CI/Jenkins、关键页面流程变更才补 DD。
113
141
  3. 开发实现
114
142
  - 只修改本次任务必要文件,不做无关重构。
115
143
  4. 本地轻量校验
@@ -117,18 +145,18 @@ workflow:
117
145
  - 若未配置,再执行 quick test / test / build 中最先配置的一项
118
146
  - `git diff --check`
119
147
  - API 文档检查
120
- - Jenkins 配置检查
148
+ - 已启用的 CI/Jenkins 配置检查
121
149
  5. 提交推送
122
- - `dev` 模式:轻量校验通过后,先写 `DEV-CLOSED` 闭环,再 commit + push,触发 Jenkins 后结束。
123
- - `verify` 模式:commit + push 后继续等待 Jenkins 和目标环境验证。
124
- 6. Jenkins 验证
125
- - 仅 `verify` 模式默认执行。看 Jenkins 构建、镜像、部署结果;失败则基于 Jenkins 日志修复并再次提交。
150
+ - `dev` 模式:轻量校验通过后,先写 `DEV-CLOSED` 闭环,再 commit + push 后结束。
151
+ - `verify` 模式:commit + push 后继续等待已启用的 CI/Jenkins 和目标环境验证。
152
+ 6. CI/Jenkins 验证
153
+ - 仅 `verify` 模式且 `verification.jenkins_required: true` 时默认执行。看 CI/Jenkins 构建、镜像、部署结果;失败则基于日志修复并再次提交。
126
154
  7. 目标环境验证
127
- - 仅 `verify` 模式默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
155
+ - 仅 `verify` 模式且 `verification.target_env_required: true` 时默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
128
156
  8. 回归与证据记录
129
- - 只有真实执行过 Jenkins / 目标环境验证,或明确要求本地运行验证时,才把 regression matrix 写成 `PASS`。
157
+ - 只有真实执行过已启用的 CI/Jenkins / 目标环境验证,或明确要求本地运行验证时,才把 regression matrix 写成 `PASS`。
130
158
  9. 闭环记录
131
- - `dev` 模式记录 `DEV-CLOSED`,表示开发闭环完成但 Jenkins/目标环境未验证。
159
+ - `dev` 模式记录 `DEV-CLOSED`,表示开发闭环完成但 CI/Jenkins/目标环境未验证。
132
160
  - `verify` 模式记录 `PASS` / `FAIL` / `PARTIAL`,必须基于真实验证结果。
133
161
 
134
162
  ## Default vs On-demand
@@ -154,20 +182,21 @@ workflow:
154
182
  1. Install skill into project:
155
183
 
156
184
  ```bash
157
- autocoding init --ai all
158
- # or: --ai codex / --ai claude
185
+ autocoding init
159
186
  ```
160
187
 
161
- For Codex installs, the command also creates `.agents/agents/` with the default `explorer`, `fixer`, `reviewer`, `docs_researcher`, and `browser_debugger` subagents.
188
+ This creates `.agents/skills/auto-coding-skill` and refreshes the managed default `explorer`, `fixer`, `reviewer`, `docs_researcher`, and `browser_debugger` subagents in `.agents/agents/`. Existing custom files in `.agents/agents/` are preserved even with `--force`.
189
+
190
+ For non-current-directory installs, `--dest` accepts a repo root, a `.agents` directory, `.agents/skills`, or the direct `.agents/skills/auto-coding-skill` directory.
162
191
 
163
192
  2. Initialize docs and local scripts:
164
193
 
165
194
  ```bash
166
195
  python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install
167
- # or
168
- python3 .claude/skills/auto-coding-skill/scripts/ap.py --repo . install
169
196
  ```
170
197
 
198
+ `install` refuses to overwrite existing generated docs/tooling unless `--force` is passed. For existing projects, use `upgrade` instead of rerunning initialization blindly.
199
+
171
200
  3. Fill only one file manually:
172
201
 
173
202
  - `docs/ENGINEERING.md` frontmatter
@@ -181,6 +210,7 @@ It must be committed to Git. Do not add it to `.gitignore`.
181
210
  - `gate.*`
182
211
  - `structure.*`
183
212
  - `optimization.*`
213
+ - `verification.*`
184
214
  - `target_env.*`
185
215
  - `jenkins.*`
186
216
  - `docs.*`
@@ -189,6 +219,10 @@ It must be committed to Git. Do not add it to `.gitignore`.
189
219
  - `workflow.mode`
190
220
  - `project.name`
191
221
  - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`,或 `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
222
+ - `verification.target_env_required`
223
+ - `verification.jenkins_required`
224
+
225
+ 仅当 `verification.target_env_required: true` 时必填:
192
226
  - `target_env.name`
193
227
  - `target_env.frontend_base_url`
194
228
  - `target_env.frontend_username`
@@ -200,6 +234,8 @@ It must be committed to Git. Do not add it to `.gitignore`.
200
234
  - `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
201
235
  - `target_env.health_base_url`
202
236
  - `target_env.health_path`
237
+
238
+ 仅当 `verification.jenkins_required: true` 时必填:
203
239
  - `jenkins.base_url`
204
240
  - `jenkins.ui_username`
205
241
  - `jenkins.ui_password` 或 `jenkins.ui_password_env`
@@ -252,6 +288,8 @@ Useful commands:
252
288
 
253
289
  ```bash
254
290
  python3 docs/tools/autopipeline/ap.py classify --scope auto
291
+ python3 docs/tools/autopipeline/ap.py docs-ledger-check
292
+ python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
255
293
  python3 docs/tools/autopipeline/ap.py structure-check --scope auto
256
294
  python3 docs/tools/autopipeline/ap.py structure-check --scope full
257
295
  python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
@@ -263,6 +301,10 @@ python3 docs/tools/autopipeline/ap.py upgrade --dry-run
263
301
  `structure-check` is intentionally generic. Project-specific paths and stricter rules belong in `docs/ENGINEERING.md` under `structure.*`, `optimization.*`, and optional `commands.structure_check`.
264
302
  Historical large-file debt can be listed in `structure.accepted_debt_paths` after it is recorded in the health baseline or optimization backlog; continued large additions to those files still fail.
265
303
 
304
+ `docs-ledger-check` is intentionally separate from `structure-check`. It treats `docs/tasks/taskbook.md`, `docs/tasks/closure-log.md`, and top-level `docs/design/T*.md` as active working sets. When they exceed `docs.active_*` budgets, the fix is physical archiving under `docs.task_archive_dir` / `docs.design_archive_dir`; `docs.archive_index` is only a navigation index and does not count as archive slimming.
305
+
306
+ Use `docs-ledger-archive --plan` first. If the plan only contains closed task sections, non-conflicting closure records, and matching top-level `T*.md` DD files, apply it with `docs-ledger-archive --write`, then rerun `docs-ledger-check`. Add `--period 2026-06` only when backfilling a specific archive month.
307
+
266
308
  ## Project Upgrade
267
309
 
268
310
  For existing projects, do not rerun initialization blindly. Use:
@@ -274,6 +316,8 @@ python3 docs/tools/autopipeline/ap.py upgrade --write
274
316
 
275
317
  `upgrade` updates autopipeline scripts, syncs project-local `.agents` skill copies when present, creates missing template docs, and merges only missing frontmatter keys into `docs/ENGINEERING.md`.
276
318
 
319
+ Use `install --force` only when intentionally resetting generated docs/tooling.
320
+
277
321
  ## Baseline And Evidence
278
322
 
279
323
  Initialize a project health baseline:
@@ -294,6 +338,7 @@ Execution evidence is written as JSONL:
294
338
  - `.local/auto-coding-skill/gate-profile.jsonl`
295
339
 
296
340
  Use `python3 docs/tools/autopipeline/ap.py gate-profile` to summarize command duration and failure history.
341
+ Use `python3 docs/tools/autopipeline/ap.py docs-ledger-check` to verify that active docs ledgers remain small enough for fast lookup. Use `python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan` before applying physical archives.
297
342
 
298
343
  ## Multi-project Sync
299
344
 
@@ -303,7 +348,7 @@ autocoding sync --projects /path/to/repo1,/path/to/repo2 --dry-run
303
348
  autocoding sync --projects /path/to/repo1,/path/to/repo2
304
349
  ```
305
350
 
306
- `status` reports drift in `.agents`, Codex agents, autopipeline scripts, missing template docs, and missing config keys. `sync` updates generated assets and creates missing docs, but leaves `docs/ENGINEERING.md` to `ap.py upgrade --write`.
351
+ `status` reports drift in `.agents`, managed agents, autopipeline scripts, missing template docs, and missing config keys. `sync` updates generated assets and creates missing docs, preserves custom files in `.agents/agents`, and leaves `docs/ENGINEERING.md` to `ap.py upgrade --write`.
307
352
 
308
353
  ## AGENTS.md Constraint Example
309
354
 
@@ -342,6 +387,7 @@ autocoding sync --projects /path/to/repo1,/path/to/repo2
342
387
  ## Default Gate Policy
343
388
  - Default local gate is lightweight only.
344
389
  - Use `python3 docs/tools/autopipeline/ap.py classify --scope auto` to classify risk, required docs, verification surfaces, and recommended commands.
390
+ - Use `python3 docs/tools/autopipeline/ap.py docs-ledger-check` when docs/task ledgers grow; use `docs-ledger-archive --plan` before `--write`; do not treat `archive-index.md` as a substitute for physical archives.
345
391
  - Use `python3 docs/tools/autopipeline/ap.py impact --scope auto` to inspect changed files, matched project rules, and selected gate scope.
346
392
  - Use `python3 docs/tools/autopipeline/ap.py structure-check --scope auto` to catch file growth, large-file extension, and missing structure baseline docs.
347
393
  - Use `python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain` for small-step development after a project declares `gate.default_scope: auto`, `commands.gate_changed`, or matching `gate.rules`.
@@ -350,7 +396,7 @@ autocoding sync --projects /path/to/repo1,/path/to/repo2
350
396
  - The structure gate is generic. Project-specific thresholds and accepted generated/vendor paths belong in `docs/ENGINEERING.md` under `structure.*`.
351
397
  - Do not require local Docker Compose or full local regression unless the task explicitly needs local runtime diagnosis.
352
398
  - In `dev` mode, push is the finish line after `DEV-CLOSED` is recorded.
353
- - In `verify` mode, Jenkins success, target environment verification, and closure record are mandatory.
399
+ - In `verify` mode, configured CI/Jenkins success, target environment verification, and closure record are mandatory only when the corresponding `verification.*_required` switch is enabled.
354
400
 
355
401
  ## Structure Policy
356
402
  - Before coding, identify the right layer and reuse points.
@@ -366,10 +412,10 @@ autocoding sync --projects /path/to/repo1,/path/to/repo2
366
412
  - Purpose: single source of project config + workflow rules.
367
413
  - How to record:
368
414
  - Fill YAML frontmatter once.
369
- - Keep target env front/backend usernames, Jenkins UI/API usernames, password fields or `*_password_env` references, commands, and docs paths here only.
415
+ - Keep target env front/backend usernames, Jenkins UI/API usernames, password fields or `*_password_env` references, commands, and docs paths here only when those verification surfaces are enabled.
370
416
  - Target environment also includes backend server root username/password.
371
417
  - This file is expected to be committed to Git; prefer `*_password_env` for secrets so actual secret values stay in the current shell.
372
- - Remaining environment keys are all mandatory; blank values, TODO-like placeholders, and incorrect URL/path formats are treated as blocking errors by `doctor`.
418
+ - Remaining enabled environment keys are mandatory; blank values, TODO-like placeholders, and incorrect URL/path formats are treated as blocking errors by `doctor`.
373
419
  - For secret fields, `doctor` requires either a direct `*_password` value or a `*_password_env` variable name. Commands that actually authenticate require the referenced environment variable to be set at execution time.
374
420
  - Do not duplicate config elsewhere.
375
421
 
@@ -378,13 +424,15 @@ autocoding sync --projects /path/to/repo1,/path/to/repo2
378
424
  - How to record:
379
425
  - Every task writes scope, risk, impact area, minimal design note, acceptance, evidence links.
380
426
  - For code changes, record structure placement, reuse check, and whether ADR is needed.
427
+ - Keep this file active-only. Closed history belongs under `docs/tasks/archives/**`; an index-only file is not enough.
381
428
 
382
429
  ### 3) docs/tasks/closure-log.md
383
430
  - Purpose: default lightweight closure record.
384
431
  - How to record:
385
432
  - Append one record per task.
386
- - Required fields: task, commit, Jenkins build, target env verification, structure check, result, follow-up.
387
- - If Jenkins failed then was fixed, also record failure reason and fix commit.
433
+ - Required fields: task, commit, configured CI/Jenkins status, target env status, structure check, result, follow-up.
434
+ - If CI/Jenkins failed then was fixed, also record failure reason and fix commit.
435
+ - Keep this file active-only. Historical closure records belong under `docs/tasks/archives/**`.
388
436
 
389
437
  ### 4) docs/architecture/
390
438
  - Files:
@@ -403,10 +451,18 @@ autocoding sync --projects /path/to/repo1,/path/to/repo2
403
451
  - Accepted debt is not a fresh blocker unless it worsened or needs priority upgrade.
404
452
 
405
453
  ### 6) docs/design/
406
- - Purpose: DD for cross-module / API / DB / deployment / Jenkins / key-page-flow changes.
454
+ - Purpose: DD for cross-module / API / DB / deployment / CI/Jenkins / key-page-flow changes.
407
455
  - How to record:
408
456
  - Small changes do not need a standalone DD file.
409
457
  - Higher-risk changes create `docs/design/<TASK_ID>-<slug>.md`.
458
+ - Keep top-level `docs/design/T*.md` active-only. Historical DDs belong under `docs/archive/design/**`.
459
+
460
+ ### 6.5) docs/tasks/archives/ and docs/archive/design/
461
+ - Purpose: physical history archives for closed taskbook entries, closure records, and old DDs.
462
+ - Rule:
463
+ - Archive by period or legacy bucket when active ledgers exceed `docs.active_*` budgets.
464
+ - `docs/tasks/archive-index.md` may summarize and link archives, but it is not the archive itself.
465
+ - `doctor` blocks over-budget active ledgers when `docs.ledger_block_on_exceed: true`.
410
466
 
411
467
  ### 7) docs/interfaces/
412
468
  - Files:
@@ -437,7 +493,7 @@ These categories require stronger verification and usually a DD:
437
493
  - Database migration
438
494
  - Authentication / authorization
439
495
  - Payment / order
440
- - Deployment / Jenkins
496
+ - Deployment / CI / Jenkins
441
497
  - Nginx / gateway
442
498
  - File upload / download
443
499
  - Production configuration
@@ -460,7 +516,7 @@ Development mode can also be forced per run:
460
516
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode dev --msg "<TASK_ID>: <summary>"
461
517
  ```
462
518
 
463
- Verification mode runs the full Jenkins + target-environment loop:
519
+ Verification mode runs the configured CI/Jenkins + target-environment loop. Disabled surfaces are recorded as skipped:
464
520
 
465
521
  ```bash
466
522
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> \
@@ -476,13 +532,15 @@ Manual verification commands remain available:
476
532
  python3 docs/tools/autopipeline/ap.py verify-jenkins-build --git-ref HEAD
477
533
  python3 docs/tools/autopipeline/ap.py wait-health --scope target
478
534
  python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
479
- python3 docs/tools/autopipeline/ap.py record-closure <TASK_ID> --commit HEAD --jenkins <build-url> --result PASS --verification "health check" --verification "key api" --verification "key page"
535
+ python3 docs/tools/autopipeline/ap.py record-closure <TASK_ID> --commit HEAD --ci-build <build-url-or-skipped> --result PASS --verification "health check" --verification "key api" --verification "key page"
480
536
  ```
481
537
 
482
538
  Available on-demand commands:
483
539
 
484
540
  ```bash
485
541
  python3 docs/tools/autopipeline/ap.py doctor
542
+ python3 docs/tools/autopipeline/ap.py docs-ledger-check
543
+ python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
486
544
  python3 docs/tools/autopipeline/ap.py verify-api-docs
487
545
  python3 docs/tools/autopipeline/ap.py verify-jenkins
488
546
  python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
@@ -496,7 +554,7 @@ python3 docs/tools/autopipeline/ap.py check-matrix
496
554
  python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
497
555
  ```
498
556
 
499
- ## Jenkins Build Tracking
557
+ ## Optional Jenkins Build Tracking
500
558
 
501
559
  - `verify-jenkins-build --git-ref HEAD`
502
560
  - Use when Jenkins build descriptions include commit SHA and you want to find the latest build automatically.
@@ -10,7 +10,7 @@ developer_instructions = """
10
10
  工作要求:
11
11
  1. 优先用 rg / git / 项目脚本快速定位真实入口,再向下追踪调用链。
12
12
  2. 先读项目已有文档、配置、路由、任务记录;涉及结构/优化时还要读结构标准、健康基线和优化 backlog。
13
- 3. 必要时运行或建议 `ap.py classify --scope auto`,说明风险级别、建议 gate scope、是否需要 DD/ADR/browser/Jenkins/target verify。
13
+ 3. 必要时运行或建议 `ap.py classify --scope auto` 和 `ap.py docs-ledger-check`,说明风险级别、建议 gate scope、是否需要 DD/ADR/browser/CI-Jenkins/target verify,以及活跃 docs ledger 是否超预算;如超预算,只建议 `docs-ledger-archive --plan`,不要直接归档。
14
14
  4. 输出根因时说明当前代码应归属的层级、现有同类模块、可复用 helper / 组件 / 脚本,以及是否触及 `structure.layer_rules`。
15
15
  5. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
16
16
  6. 输出内容必须尽量具体到:
@@ -18,7 +18,7 @@ developer_instructions = """
18
18
  8. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
19
19
  9. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
20
20
  10. 如果修改涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界,交给 reviewer / 安全能力做只读复核。
21
- 11. 修改后运行聚焦门禁:优先项目 light gate,其次 structure-check、相关测试、typecheck、lint、git diff --check,并确保 evidence.jsonl 记录实际执行。
21
+ 11. 修改后运行聚焦门禁:优先项目 light gate,其次 docs-ledger-check、structure-check、相关测试、typecheck、lint、git diff --check,并确保 evidence.jsonl 记录实际执行;docs ledger 超预算时先输出 `docs-ledger-archive --plan`,只有主代理或用户确认后才执行 `--write`。
22
22
  12. 修改后输出:
23
23
  - 修改文件
24
24
  - 修改点
@@ -11,14 +11,15 @@ developer_instructions = """
11
11
  1. 优先检查:正确性、安全性、边界条件、异常路径、并发风险、事务一致性、缓存一致性、兼容性。
12
12
  2. 结构/优化 review 必须先读 project-health-baseline 和 optimization-backlog;不要把 accepted debt 重新报告为当前 blocker。
13
13
  3. 检查 `docs/tasks/evidence.jsonl`、closure-log 和实际命令输出是否一致;不要把未执行项写成 PASS。
14
- 4. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
15
- 5. 以 git diff、相关测试、接口契约、真实运行证据、结构标准为基础,不凭风格偏好输出问题。
16
- 6. 优先输出真实问题,不要输出样式洁癖式意见。
17
- 7. 每条问题尽量包含:
14
+ 4. 检查活跃 docs ledger 是否超过预算;`archive-index.md` 只是导航,不能替代 `docs/tasks/archives/**` 和 `docs/archive/design/**` 物理归档;需要归档时要求先审阅 `docs-ledger-archive --plan` 输出。
15
+ 5. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
16
+ 6. 以 git diff、相关测试、接口契约、真实运行证据、结构标准为基础,不凭风格偏好输出问题。
17
+ 7. 优先输出真实问题,不要输出样式洁癖式意见。
18
+ 8. 每条问题尽量包含:
18
19
  - 问题点
19
20
  - 影响范围
20
21
  - 复现条件
21
22
  - 建议修法
22
- 8. 发现测试不足时,指出应补哪些测试或验证路径。
23
- 9. 结论要按严重程度排序:P0 / P1 / P2 / P3,并明确是否影响当前任务完成。
23
+ 9. 发现测试不足时,指出应补哪些测试或验证路径。
24
+ 10. 结论要按严重程度排序:P0 / P1 / P2 / P3,并明确是否影响当前任务完成。
24
25
  """
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: auto-coding-skill
3
- description: Use for a Claude/Codex engineering workflow with dev and verify modes. Initialize docs, fill docs/ENGINEERING.md once, then execute task->minimal-design->light-gate->DEV-CLOSED->push in dev mode, or full Jenkins->target-env->PASS closure in verify mode.
3
+ description: Use for a generic .agents engineering workflow with dev and verify modes. Initialize docs, fill docs/ENGINEERING.md once, then execute task->minimal-design->light-gate->DEV-CLOSED->push in dev mode, or full configured verification closure in verify mode.
4
4
  ---
5
5
 
6
- # Auto Coding Skill (Claude + Codex)
6
+ # Auto Coding Skill (.agents)
7
7
 
8
- This skill is for Go backend + frontend monorepo projects that rely on Jenkins to build and deploy after push. It supports both Claude and Codex. The default `dev` mode is optimized for fast development: lightweight local gate, early closure record, commit, push, then move to the next task. Use `verify` mode when Jenkins and the real target environment must be completed before closure.
8
+ This skill is for general software projects that need a disciplined task -> design -> implementation -> verification -> closure workflow. The default target is the shared `.agents/skills` and `.agents/agents` layout, independent of the client that loads it. The default `dev` mode is optimized for fast development: lightweight local gate, early closure record, commit, push, then move to the next task. Use `verify` mode when configured CI/Jenkins and real target environment checks must be completed before closure.
9
9
 
10
- `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory, must be filled with real values, and are committed as part of the project baseline. Secret fields may be represented either as direct `*_password` values for legacy projects or as `*_password_env` names that point to environment variables in the current shell. Unused environment keys should be removed from the template instead of being left as placeholders.
10
+ `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory only when their verification surface is enabled. Secret fields may be represented either as direct `*_password` values for legacy projects or as `*_password_env` names that point to environment variables in the current shell. Unused environment keys should be removed from the template instead of being left as placeholders.
11
11
 
12
12
  At task start, inventory the current client capabilities before choosing a route: installed MCP servers, local skills, plugins/apps/connectors, browser/control tools, and repo scripts. Prefer those capabilities when they provide current, authoritative, or directly inspectable state.
13
13
 
@@ -15,8 +15,7 @@ Use multi-agent roles deliberately. When the client exposes subagent tools and t
15
15
 
16
16
  ## Supported clients
17
17
 
18
- - Claude Code
19
- - Codex CLI
18
+ - Any agent client or local workflow that reads the shared `.agents` layout.
20
19
 
21
20
  ## Tooling policy
22
21
 
@@ -25,7 +24,7 @@ Use the most direct authoritative capability for each task:
25
24
  1) Local repo work: use shell, repo scripts, and `docs/tools/autopipeline/ap.py` for edits, tests, gates, git, and project-local verification.
26
25
  2) Current library/framework/API/CLI/cloud behavior: use a documentation MCP such as Context7 or the matching installed skill before coding migrations, config changes, or API integrations.
27
26
  3) Browser and UI verification: use Browser/in-app browser for localhost and app-owned sessions; use Chrome when the user's existing logged-in Chrome state is required; use Playwright for deterministic browser automation or terminal-first smoke tests; use Computer Use only for native apps or UI surfaces without a purpose-built connector.
28
- 4) Product/design sources: use Figma, Build Web Apps, Product Design, or frontend skills when the task depends on design context, visual implementation, screenshots, or generated UI.
27
+ 4) Product/design sources: use Figma, Build Web Apps, Product Design, or frontend/product-design skills when the task depends on design context, visual implementation, screenshots, or generated UI.
29
28
  5) GitHub/PR/CI state: use GitHub connectors for PRs, issues, review comments, and Actions/CI metadata; use local git for local diff, staging, commits, and pushes.
30
29
  6) Security-sensitive changes: use reviewer/security skills or security scan capabilities for auth, permission, payment, file transfer, deployment, dependency, and data-boundary changes.
31
30
  7) Analytical or document artifacts: use Data Analytics, documents, PDFs, spreadsheets, presentations, or LaTeX skills/plugins for those artifact types, including render/validation steps.
@@ -35,7 +34,7 @@ Use the most direct authoritative capability for each task:
35
34
 
36
35
  ## Collaboration policy
37
36
 
38
- Use `.agents/agents` role templates as the default collaboration model for Codex installs:
37
+ Use `.agents/agents` role templates as the default collaboration model:
39
38
 
40
39
  1) `explorer`: read-only repo discovery, call-chain tracing, config mapping, and root-cause candidates.
41
40
  2) `docs_researcher`: current external documentation, API signatures, version behavior, and compatibility checks.
@@ -43,27 +42,27 @@ Use `.agents/agents` role templates as the default collaboration model for Codex
43
42
  4) `fixer`: bounded implementation after the cause and acceptance path are clear.
44
43
  5) `reviewer`: read-only correctness, security, regression-risk, and missing-test review.
45
44
 
46
- The main agent always owns task framing, design decisions, integration, Jenkins / target-env verification, closure records, git state, and final delivery. Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
45
+ The main agent always owns task framing, design decisions, integration, configured CI / target-env verification, closure records, git state, and final delivery. Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
47
46
 
48
47
  ## Entry
49
48
 
50
49
  1) Install skill files into target repo:
51
50
 
52
51
  ```bash
53
- autocoding init --ai codex
54
- # or claude / all
52
+ autocoding init
55
53
  ```
56
54
 
57
- For Codex targets, this also installs the default subagent templates into `.agents/agents/`.
55
+ This also installs the managed default subagent templates into `.agents/agents/`. Existing custom agent files in `.agents/agents/` are preserved even when `--force` is used; managed template files with the same names are refreshed.
56
+
57
+ For non-current-directory installs, `--dest` accepts a repo root, a `.agents` directory, `.agents/skills`, or the direct `.agents/skills/auto-coding-skill` directory.
58
58
 
59
59
  2) Initialize docs/tooling:
60
60
 
61
61
  ```bash
62
62
  python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install
63
- # or .claude path
64
63
  ```
65
64
 
66
- Existing projects should use upgrade mode before replacing tracked docs:
65
+ `install` refuses to overwrite existing generated docs/tooling unless `--force` is passed. Existing projects should use upgrade mode before replacing tracked docs:
67
66
 
68
67
  ```bash
69
68
  python3 docs/tools/autopipeline/ap.py upgrade --dry-run
@@ -88,9 +87,10 @@ This contains all manual fields:
88
87
  - `gate.*`
89
88
  - `structure.*`
90
89
  - `optimization.*`
90
+ - `verification.*`
91
91
  - `runtime.*` (only for optional local diagnostics)
92
- - `target_env.*`
93
- - `jenkins.*`
92
+ - `target_env.*` (only required when `verification.target_env_required: true`)
93
+ - `jenkins.*` (only required when `verification.jenkins_required: true`)
94
94
  - `docs.*`
95
95
 
96
96
  Do not duplicate config in other md/yaml files.
@@ -100,6 +100,10 @@ Minimum required config for the default flow:
100
100
  - `workflow.mode`
101
101
  - `project.name`
102
102
  - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`, or `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
103
+ - `verification.target_env_required`
104
+ - `verification.jenkins_required`
105
+
106
+ Required only when `verification.target_env_required: true`:
103
107
  - `target_env.name`
104
108
  - `target_env.frontend_base_url`
105
109
  - `target_env.frontend_username`
@@ -111,6 +115,8 @@ Minimum required config for the default flow:
111
115
  - `target_env.backend_root_password` or `target_env.backend_root_password_env`
112
116
  - `target_env.health_base_url`
113
117
  - `target_env.health_path`
118
+
119
+ Required only when `verification.jenkins_required: true`:
114
120
  - `jenkins.base_url`
115
121
  - `jenkins.ui_username`
116
122
  - `jenkins.ui_password` or `jenkins.ui_password_env`
@@ -138,7 +144,7 @@ Read `workflow.mode` from `docs/ENGINEERING.md` before choosing the path.
138
144
  2) run or reason through `classify --scope auto` for changed work
139
145
  3) read `docs/architecture/structure-standard.md` when the change adds or relocates code
140
146
  4) read / update `docs/tasks/taskbook.md`
141
- 5) write minimal design notes; create a DD or ADR only when the change is cross-module, API, DB, deployment, Jenkins, key-page-flow, or long-term structure related
147
+ 5) write minimal design notes; create a DD or ADR only when the change is cross-module, API, DB, deployment, CI/Jenkins, key-page-flow, or long-term structure related
142
148
  6) implement only the necessary changes
143
149
  7) run the default local lightweight gate
144
150
  8) append `docs/tasks/closure-log.md` with `Result: DEV-CLOSED`
@@ -150,8 +156,8 @@ Read `workflow.mode` from `docs/ENGINEERING.md` before choosing the path.
150
156
  1) read / update the same authoritative docs
151
157
  2) run the default local lightweight gate
152
158
  3) commit + push
153
- 4) verify Jenkins build / deployment result
154
- 5) verify the real target environment
159
+ 4) verify configured CI/Jenkins build / deployment result when enabled
160
+ 5) verify the real target environment when enabled
155
161
  6) append `docs/tasks/closure-log.md` with `Result: PASS / FAIL / PARTIAL`
156
162
  7) use summary / deployment record / regression matrix only when the task actually requires them
157
163
 
@@ -163,6 +169,8 @@ Default commands:
163
169
  python3 docs/tools/autopipeline/ap.py doctor
164
170
  python3 docs/tools/autopipeline/ap.py classify --scope auto
165
171
  python3 docs/tools/autopipeline/ap.py impact --scope auto
172
+ python3 docs/tools/autopipeline/ap.py docs-ledger-check
173
+ python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
166
174
  python3 docs/tools/autopipeline/ap.py structure-check --scope auto
167
175
  python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
168
176
  python3 docs/tools/autopipeline/ap.py light-gate --scope full
@@ -179,6 +187,7 @@ python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
179
187
  python3 docs/tools/autopipeline/ap.py runtime-down
180
188
  python3 docs/tools/autopipeline/ap.py upgrade --dry-run
181
189
  python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
190
+ python3 docs/tools/autopipeline/ap.py docs-ledger-archive --write
182
191
  python3 docs/tools/autopipeline/ap.py structure-check --scope full
183
192
  python3 docs/tools/autopipeline/ap.py gate-profile
184
193
  python3 docs/tools/autopipeline/ap.py check-matrix
@@ -197,27 +206,31 @@ python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
197
206
  - For structural reviews, read `docs/reviews/project-health-baseline.md` and `docs/reviews/optimization-backlog.md` first. Do not re-report accepted debt as a fresh blocker; report only new, worsened, unrecorded P0/P1, or backlog items that now deserve priority upgrade.
198
207
  - “Optimization complete” means the scoped P0/P1/P2 work is closed, local gate passes, no new unclassified P0/P1 exists, and remaining P2/P3 work is tracked or accepted debt.
199
208
  - `baseline init` creates the first project health baseline and optimization backlog; use `--update-config` to seed `accepted_debt_paths`.
209
+ - `docs-ledger-check` enforces active documentation ledger budgets. `docs/tasks/taskbook.md`, `docs/tasks/closure-log.md`, and top-level `docs/design/T*.md` are active working sets, not unbounded history stores.
210
+ - When active ledger budgets are exceeded, run `docs-ledger-archive --plan`, inspect the plan, then run `docs-ledger-archive --write` only when the closed entries and DD files are correct. Add `--period 2026-06` only when backfilling a specific archive month. The archiver handles clearly closed task sections, non-conflicting closure records, and matching top-level `T*.md` DDs.
211
+ - `docs.archive_index` is only navigation; an index without physical archive files does not satisfy ledger health.
200
212
  - `docs/tasks/evidence.jsonl` is the machine-readable execution trail for gates, verification, and closure. Keep it aligned with closure Markdown.
201
213
  - `gate-profile` summarizes local gate duration and failure history so small-step development can keep the fast path honest.
202
214
 
203
215
  ## Quality policy
204
216
 
205
- - Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/Jenkins checks.
217
+ - Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/config checks.
206
218
  - For small-step development, prefer the generic impact-aware gate: `light-gate --scope auto`. The skill provides the gate engine; each project owns its commands and optional `gate.rules` path mapping in `docs/ENGINEERING.md`.
207
219
  - `light-gate` automatically runs `structure-check` when `structure.enabled: true` or `commands.structure_check` is configured.
208
220
  - Keep `standard` as the backward-compatible default when no `gate.*` policy is configured. Use `changed` only when project commands/rules make the reduced scope explicit.
209
221
  - Automatically upgrade to `full` for CI/deploy/build-tool/lockfile/autopipeline config changes, project-declared full rules, unknown impact when configured, or release/verify tasks.
210
222
  - `workflow.mode: dev` closes development after light gate, closure record, commit, and push.
211
- - `workflow.mode: verify` closes only after Jenkins and target-environment verification.
223
+ - `workflow.mode: verify` closes only after the configured CI/Jenkins and target-environment verification surfaces are satisfied.
212
224
  - `doctor` should be used early to catch missing or invalid config before the first implementation loop.
225
+ - `doctor` runs the built-in docs ledger health check by default so projects do not accumulate giant taskbooks, closure logs, or active DD directories.
213
226
  - `light-gate` now fails if no usable fast gate command is configured.
214
227
  - `doctor`, `light-gate`, and `commit-push` all fail when required environment fields are missing, placeholder-like, or syntactically invalid.
215
228
  - Do not require local Docker Compose or full local regression for every small change.
216
- - Jenkins and target environment verification are mandatory in `verify` mode, not in default `dev` mode.
229
+ - CI/Jenkins and target environment verification are mandatory in `verify` mode only when `verification.jenkins_required` / `verification.target_env_required` are enabled.
217
230
  - `verify-target` should be used for real target-environment API/page checks when the task touches user-visible or deploy-sensitive behavior.
218
231
  - `commit-push` records closure automatically according to `workflow.mode`.
219
232
  - `regression-matrix.md` can mark `PASS` only after real execution with evidence.
220
- - High-risk changes must include target environment verification and usually a DD.
233
+ - High-risk changes must include a DD and the strongest configured verification path; target-environment verification is required when `verification.target_env_required: true` or the task explicitly depends on runtime behavior.
221
234
 
222
235
  ## Multi-project operations
223
236
 
@@ -229,4 +242,4 @@ autocoding sync --projects /path/to/repo1,/path/to/repo2 --dry-run
229
242
  autocoding sync --projects /path/to/repo1,/path/to/repo2
230
243
  ```
231
244
 
232
- `status` reports drift in project-local `.agents`, Codex agent templates, autopipeline scripts, missing template docs, and missing config keys. `sync` updates generated skill/tooling assets and only creates missing docs; it does not overwrite project-specific `docs/ENGINEERING.md`, which should be merged through `ap.py upgrade --write`.
245
+ `status` reports drift in project-local `.agents`, managed agent templates, autopipeline scripts, missing template docs, and missing config keys. `sync` updates generated skill/tooling assets and only creates missing docs; it preserves custom files in `.agents/agents` and does not overwrite project-specific `docs/ENGINEERING.md`, which should be merged through `ap.py upgrade --write`.