@elvis1513/auto-coding-skill 2.1.3 → 2.2.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.
Files changed (30) hide show
  1. package/README.md +154 -548
  2. package/cli/assets/agents/browser-debugger.toml +0 -1
  3. package/cli/assets/agents/docs-researcher.toml +0 -1
  4. package/cli/assets/agents/explorer.toml +1 -2
  5. package/cli/assets/agents/fixer.toml +2 -3
  6. package/cli/assets/agents/reviewer.toml +1 -2
  7. package/cli/assets/skill/SKILL.md +98 -207
  8. package/cli/assets/skill/data/templates/ENGINEERING.md +113 -468
  9. package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +11 -22
  10. package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +16 -39
  11. package/cli/assets/skill/data/templates/tools/ap.py +16 -0
  12. package/cli/assets/skill/scripts/ap.py +666 -129
  13. package/cli/assets/skill/scripts/scaffold_templates.py +136 -0
  14. package/cli/src/index.js +317 -42
  15. package/cli/tests/ap_profiles_test.py +428 -0
  16. package/cli/tests/index.test.js +373 -62
  17. package/package.json +3 -3
  18. package/cli/assets/skill/data/templates/docs/architecture/adr/_TEMPLATE-ADR.md +0 -38
  19. package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +0 -92
  20. package/cli/assets/skill/data/templates/docs/bugs/bug-list.md +0 -5
  21. package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +0 -19
  22. package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +0 -11
  23. package/cli/assets/skill/data/templates/docs/design/_TEMPLATE-DD.md +0 -49
  24. package/cli/assets/skill/data/templates/docs/interfaces/api-change-log.md +0 -11
  25. package/cli/assets/skill/data/templates/docs/interfaces/api.md +0 -36
  26. package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +0 -36
  27. package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +0 -25
  28. package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +0 -66
  29. package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +0 -35
  30. package/cli/assets/skill/data/templates/docs/testing/regression-matrix.md +0 -11
package/README.md CHANGED
@@ -1,623 +1,229 @@
1
1
  # auto-coding-skill
2
2
 
3
- Engineering workflow skill for:
4
-
5
- - shared `.agents` skills and role templates
6
-
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.
8
-
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.
3
+ A generic `.agents` engineering workflow with adaptive execution profiles,
4
+ minimal project scaffolding, evidence-backed closure, and optional CI/Jenkins and
5
+ target-environment verification.
6
+
7
+ ## What changed in v2.2.0
8
+
9
+ - Added `micro`, `standard`, and `high-risk` execution profiles.
10
+ - `workflow.profile: auto` classifies changed work and cannot downgrade detected
11
+ high-risk changes.
12
+ - High-risk and explicit verify work now require a real `gate_full`/`full_gate`;
13
+ light and standard commands are no longer accepted as full-gate fallbacks.
14
+ - Generic structure checks are advisory by default. Projects can opt into
15
+ blocking enforcement.
16
+ - Reduced a new project scaffold from 46 files / about 10,120 lines to 20 files /
17
+ about 5,300 lines.
18
+ - Replaced duplicated repository-side Python tools with a small launcher that
19
+ delegates to the single project-local skill runtime.
20
+ - Kept only ENGINEERING, taskbook, and closure log in the default documentation
21
+ scaffold; all specialized documents are materialized on demand.
22
+ - Removed hard-coded model names from managed Agent templates. New installs
23
+ inherit the active client model; existing project model overrides survive sync.
24
+ - Added behavioral regression tests for profile resolution, strict full gates,
25
+ advisory structure checks, minimal scaffold budgets, on-demand docs, and Agent
26
+ model inheritance.
10
27
 
11
28
  ## Install
12
29
 
13
30
  ```bash
14
31
  npm install -g @elvis1513/auto-coding-skill
32
+ autocoding init
33
+ autocoding sync --projects .
34
+ pip install pyyaml requests
15
35
  ```
16
36
 
17
- Fallback:
37
+ `autocoding init` installs the project-local skill and five managed roles under
38
+ `.agents`. `autocoding sync` installs the minimal project scaffold:
18
39
 
19
- ```bash
20
- npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
40
+ ```text
41
+ .agents/skills/auto-coding-skill/
42
+ .agents/agents/
43
+ docs/ENGINEERING.md
44
+ docs/tasks/taskbook.md
45
+ docs/tasks/closure-log.md
46
+ docs/tools/autopipeline/ap.py
21
47
  ```
22
48
 
23
- ## Release Notes
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
-
54
- ### v2.1.0
55
-
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.
57
- - Added baseline initialization: `ap.py baseline init --write --update-config` scans large files/hotspots, creates health baseline + optimization backlog, and can seed `structure.accepted_debt_paths`.
58
- - Added configurable structure import-boundary checks through `structure.layer_rules`.
59
- - Added local gate profiling: configured gate commands write `.local/auto-coding-skill/gate-profile.jsonl`, summarized by `ap.py gate-profile`.
60
- - Added multi-project npm CLI operations: `autocoding status --projects ...` and `autocoding sync --projects ...`.
61
- - Added structured evidence logging to `docs/tasks/evidence.jsonl` for classify, doctor, structure-check, gates, verification, and closure.
62
- - Added task classification: `ap.py classify --scope auto` reports risk, categories, required DD/ADR/browser/Jenkins/target checks, and recommended commands.
63
-
64
- ### v2.0.6
65
-
66
- - Fixed `structure-check --json` so successful output stays machine-readable JSON without a trailing OK line.
67
- - Moved CLI error messages to stderr, preserving JSON stdout for failing machine-readable commands.
68
- - Made `structure.enabled: false` disable structure gate integration even when `commands.structure_check` is still present.
69
-
70
- ### v2.0.5
71
-
72
- - Added generic engineering-structure governance: `docs/architecture/structure-standard.md`, ADR template, project health baseline, and optimization backlog templates.
73
- - Added `ap.py structure-check --scope auto|changed|standard|full` for large-file thresholds, large-file growth blocking, function-size warnings, and baseline-doc checks.
74
- - Integrated `structure-check` into `light-gate` when `structure.enabled: true` or `commands.structure_check` is configured.
75
- - Added baseline-aware optimization policy so “optimization complete” means scoped P0/P1/P2 closure plus tracked/accepted remaining debt, not “no future optimizations exist.”
76
-
77
- ### v2.0.4
78
-
79
- - Added a generic impact-aware gate engine: `ap.py impact`, `light-gate --scope auto|changed|standard|full`, and `--explain`.
80
- - Added project-owned `gate.*` policy support in `docs/ENGINEERING.md`; the skill chooses scope, while each project declares its own commands and optional path rules.
81
- - Kept backward compatibility: projects without `gate.*` continue to use the existing standard `commands.light_gate` / quick-test fallback.
82
- - Added conservative full-gate upgrades for CI, deploy, Docker, lockfile, build-tool, and autopipeline config changes.
83
-
84
- ### v2.0.3
85
-
86
- - Fixed `doctor`, `light-gate`, `verify-target`, and Jenkins API verification to accept secret references via `*_password_env`.
87
- - Kept direct `*_password` fields compatible for legacy projects while making the default template use environment-variable secret references.
88
- - Updated docs so `docs/ENGINEERING.md` can stay Git-tracked without requiring committed secrets.
89
-
90
- ### v2.0.2
91
-
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`.
95
- - Added concrete capability routing for MCP servers, installed skills, plugins/apps/connectors, browser tools, GitHub, Figma, security review, and artifact workflows.
96
- - Changed multi-agent guidance from unconditional delegation to a role model that works either as real subagents or as sequential main-agent phases.
97
- - Hardened CLI help/argument validation, asset sync checks, and stricter autopipeline config diagnostics.
49
+ The `docs/tools` entry point is a compatibility launcher. Runtime code lives only
50
+ under `.agents/skills/auto-coding-skill/scripts`.
98
51
 
99
- ### v2.0.1
52
+ ## Execution profiles
100
53
 
101
- - Updated the installer target to `.agents/skills`, matching current global and project skill discovery.
102
-
103
- ### v0.3.1
104
-
105
- - Added Jenkins crumb / CSRF retry support for API verification requests.
106
- - Added finer-grained Jenkins folder / multibranch pipeline resolution.
107
- - Added multibranch root job + branch child job support, with current Git branch inference when needed.
108
- - Kept existing `verify-jenkins-build --git-ref` and direct `--job-url` / `--build-number` flows compatible.
109
-
110
- ### v0.3.0
111
-
112
- - Synced reusable workflow improvements from a production project back into this skill.
113
- - Moved repo-side helper entrypoint to `docs/tools/autopipeline`.
114
- - Tightened regression matrix rules: rows start as `TODO`, and `PASS` requires real execution evidence.
115
- - Added Jenkins API verification flow with credentials sourced from `docs/ENGINEERING.md`.
116
-
117
- ## Optimized Standard Flow
118
-
119
- 模式由 `docs/ENGINEERING.md` 顶部控制:
54
+ Configure the selector in `docs/ENGINEERING.md`:
120
55
 
121
56
  ```yaml
122
57
  workflow:
123
- mode: "dev" # dev | verify
124
- ```
125
-
126
- `dev` 默认闭环:
127
-
128
- `需求/任务记录 -> 最小设计 -> 开发 -> 本地轻量校验 -> 写 DEV-CLOSED 闭环 -> commit/push -> 结束`
129
-
130
- `verify` 完整闭环:
131
-
132
- `需求/任务记录 -> 最小设计 -> 开发 -> 本地轻量校验 -> commit/push -> 已启用的 CI/Jenkins 验证 -> 已启用的目标环境验证 -> 写 PASS 闭环`
133
-
134
- 具体执行顺序:
135
-
136
- 1. 需求确认
137
- - 明确任务范围、影响服务、是否涉及 API / 数据库 / 部署 / CI/Jenkins / 前端页面。
138
- 2. 最小设计记录
139
- - 普通小改动只更新 `taskbook` 或相关设计文档的一小段。
140
- - 跨模块、接口、数据库、部署、CI/Jenkins、关键页面流程变更才补 DD。
141
- 3. 开发实现
142
- - 只修改本次任务必要文件,不做无关重构。
143
- 4. 本地轻量校验
144
- - 优先执行一个项目自定义快速门禁命令
145
- - 若未配置,再执行 quick test / test / build 中最先配置的一项
146
- - `git diff --check`
147
- - API 文档检查
148
- - 已启用的 CI/Jenkins 配置检查
149
- 5. 提交推送
150
- - `dev` 模式:轻量校验通过后,先写 `DEV-CLOSED` 闭环,再 commit + push 后结束。
151
- - `verify` 模式:commit + push 后继续等待已启用的 CI/Jenkins 和目标环境验证。
152
- 6. CI/Jenkins 验证
153
- - 仅 `verify` 模式且 `verification.jenkins_required: true` 时默认执行。看 CI/Jenkins 构建、镜像、部署结果;失败则基于日志修复并再次提交。
154
- 7. 目标环境验证
155
- - 仅 `verify` 模式且 `verification.target_env_required: true` 时默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
156
- 8. 回归与证据记录
157
- - 只有真实执行过已启用的 CI/Jenkins / 目标环境验证,或明确要求本地运行验证时,才把 regression matrix 写成 `PASS`。
158
- 9. 闭环记录
159
- - `dev` 模式记录 `DEV-CLOSED`,表示开发闭环完成但 CI/Jenkins/目标环境未验证。
160
- - `verify` 模式记录 `PASS` / `FAIL` / `PARTIAL`,必须基于真实验证结果。
161
-
162
- ## Default vs On-demand
163
-
164
- 默认不做:
165
- - 本地 Docker Compose 启动
166
- - 本地 Docker build
167
- - 本地完整 regression
168
- - 每个小改动强制 `check-matrix`
169
- - 每个小改动强制生成 summary
170
- - 未真实执行就要求 regression matrix 全 `PASS`
171
- - 未真实部署目标环境就生成 deployment record
172
-
173
- 按需保留:
174
- - `runtime-up` / `runtime-down`
175
- - 本地 health
176
- - `check-matrix`
177
- - `gen-summary`
178
- - deployment runbook / deployment record
179
-
180
- ## Standard Workflow
181
-
182
- 1. Install skill into project:
183
-
184
- ```bash
185
- autocoding init
58
+ mode: dev
59
+ profile: auto
186
60
  ```
187
61
 
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`.
62
+ | Effective profile | Intended work | Gate scope | Mode |
63
+ | --- | --- | --- | --- |
64
+ | `micro` | docs/tests-only or explicitly isolated work | changed | dev |
65
+ | `standard` | normal feature and defect work | standard | dev |
66
+ | `high-risk` | DB/auth/payment/file transfer/gateway/prod/deploy/build changes | full | verify |
189
67
 
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.
68
+ `auto` is a selector, not a fourth effective profile. Full-path patterns,
69
+ high-risk categories, `gate.rules[].profile: high-risk`, and explicit verify work
70
+ raise the plan to `high-risk`. A CLI `--profile micro` or `--mode dev` cannot
71
+ lower it.
191
72
 
192
- 2. Initialize docs and local scripts:
73
+ An explicit configured `micro`, `standard`, or `high-risk` profile replaces
74
+ auto's low/normal baseline and acts as a floor for CLI overrides. Independently
75
+ detected high-risk signals still force `high-risk`.
193
76
 
194
- ```bash
195
- python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install
196
- ```
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
-
200
- 3. Fill only one file manually:
201
-
202
- - `docs/ENGINEERING.md` frontmatter
203
-
204
- This frontmatter is the only manual config source.
205
- It must be committed to Git. Do not add it to `.gitignore`.
206
-
207
- 重点字段:
208
- - `workflow.mode`
209
- - `commands.*`
210
- - `gate.*`
211
- - `structure.*`
212
- - `optimization.*`
213
- - `verification.*`
214
- - `target_env.*`
215
- - `jenkins.*`
216
- - `docs.*`
217
-
218
- 默认必填:
219
- - `workflow.mode`
220
- - `project.name`
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` 时必填:
226
- - `target_env.name`
227
- - `target_env.frontend_base_url`
228
- - `target_env.frontend_username`
229
- - `target_env.frontend_password` 或 `target_env.frontend_password_env`
230
- - `target_env.backend_base_url`
231
- - `target_env.backend_username`
232
- - `target_env.backend_password` 或 `target_env.backend_password_env`
233
- - `target_env.backend_root_username`
234
- - `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
235
- - `target_env.health_base_url`
236
- - `target_env.health_path`
237
-
238
- 仅当 `verification.jenkins_required: true` 时必填:
239
- - `jenkins.base_url`
240
- - `jenkins.ui_username`
241
- - `jenkins.ui_password` 或 `jenkins.ui_password_env`
242
- - `jenkins.api_user`
243
- - `jenkins.api_password` 或 `jenkins.api_password_env`
244
- - `jenkins.trigger_branch`
245
- - `jenkins.image_repository`
246
- - `jenkins.image_tag_strategy`
247
- - `jenkins.deploy_env`
248
- - `jenkins.job_url`
249
-
250
- 4. Start AI development by constraints:
251
-
252
- - `docs/ENGINEERING.md`
253
- - `docs/architecture/structure-standard.md`
254
- - `docs/reviews/project-health-baseline.md`
255
- - `docs/reviews/optimization-backlog.md`
256
- - `docs/tasks/taskbook.md`
257
- - `docs/tasks/closure-log.md`
258
- - `docs/interfaces/**`
259
- - `docs/testing/regression-matrix.md`
260
- - `docs/bugs/bug-list.md`
261
-
262
- 5. Tool selection rule during execution:
263
-
264
- - Local code, tests, git, and project gates: use shell, repo scripts, and `docs/tools/autopipeline/ap.py`.
265
- - Current library/framework/API/CLI/cloud docs: use Context7 or the matching installed skill before coding against uncertain behavior.
266
- - UI verification: use Browser/in-app browser for local pages, Chrome for the user's logged-in Chrome state, Playwright for deterministic automation, and Computer Use only for native or unsupported UI surfaces.
267
- - GitHub/PR/CI: use GitHub connectors for remote PR, issue, review, and CI state; use local git for local diff, commit, and push.
268
- - Figma/frontend/design, security review, data/reporting, and document artifacts: use the matching installed plugin or skill before manual recreation.
269
- - Fall back to shell/manual work only when those capabilities are unavailable, insufficient, unreliable, or slower than direct execution.
270
-
271
- 6. Collaboration rule during execution:
272
-
273
- - Use `.agents/agents` as the default role model: `explorer`, `docs_researcher`, `browser_debugger`, `fixer`, `reviewer`.
274
- - If the client permits subagents, split independent work across those roles.
275
- - If the client cannot run subagents, execute the same role sequence in the main agent.
276
- - Keep one main agent responsible for scope, integration, quality gates, docs closure, git state, and final delivery.
277
-
278
- ## Structure Governance
279
-
280
- The default project scaffold includes a generic professional structure standard:
281
-
282
- - `docs/architecture/structure-standard.md`: layer boundaries, reuse-first rules, file/function size rules, and review priority definitions.
283
- - `docs/architecture/adr/_TEMPLATE-ADR.md`: architectural decision record template.
284
- - `docs/reviews/project-health-baseline.md`: accepted current structure, closed optimizations, accepted debt, and completion standard.
285
- - `docs/reviews/optimization-backlog.md`: ongoing P0/P1/P2/P3 optimization backlog.
286
-
287
- Useful commands:
77
+ Inspect the plan:
288
78
 
289
79
  ```bash
290
80
  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
293
- python3 docs/tools/autopipeline/ap.py structure-check --scope auto
294
- python3 docs/tools/autopipeline/ap.py structure-check --scope full
295
- python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
296
- python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
297
- python3 docs/tools/autopipeline/ap.py gate-profile
298
- python3 docs/tools/autopipeline/ap.py upgrade --dry-run
81
+ python3 docs/tools/autopipeline/ap.py impact --scope auto --json
299
82
  ```
300
83
 
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`.
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.
303
- Do not split files only to reduce line count. Split only when a clear business or technical boundary improves cohesion and change safety; keep cohesive transaction, state-machine, workflow, or test-scenario code together and track it as accepted debt when appropriate.
304
-
305
- `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.
84
+ Each result includes the effective profile, mode, gate scope, reasons, required
85
+ verification surfaces, and recommended Agent roles.
306
86
 
307
- 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.
87
+ ## Gate configuration
308
88
 
309
- ## Project Upgrade
310
-
311
- For existing projects, do not rerun initialization blindly. Use:
89
+ ```yaml
90
+ commands:
91
+ gate_changed: "npm run test:changed"
92
+ gate_standard: "npm test"
93
+ gate_full: "npm run test:full"
312
94
 
313
- ```bash
314
- python3 docs/tools/autopipeline/ap.py upgrade --dry-run
315
- python3 docs/tools/autopipeline/ap.py upgrade --write
95
+ gate:
96
+ default_scope: auto
97
+ rules:
98
+ - name: payments
99
+ paths: ["src/payments/**"]
100
+ profile: high-risk
316
101
  ```
317
102
 
318
- `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`.
103
+ For Node projects, a new scaffold can infer changed/standard commands from
104
+ `test`, `test:changed`, and `test:standard`. It only infers a full command from a
105
+ dedicated `test:full` script; ordinary `npm test` is never promoted to full.
106
+ A high-risk or verify run fails clearly when no real full command is configured.
319
107
 
320
- Use `install --force` only when intentionally resetting generated docs/tooling.
108
+ ## Structure policy
321
109
 
322
- ## Baseline And Evidence
110
+ The generic checker remains useful for surfacing large files, large additions,
111
+ function-size signals, and import-direction heuristics, but it is not universally
112
+ authoritative:
323
113
 
324
- Initialize a project health baseline:
325
-
326
- ```bash
327
- python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
114
+ ```yaml
115
+ structure:
116
+ enabled: true
117
+ enforcement: advisory # advisory | blocking
118
+ architecture_standard: project-defined
328
119
  ```
329
120
 
330
- This creates:
121
+ `advisory` reports findings without blocking. Projects with reliable, tailored
122
+ rules can opt into `blocking`. Repository-native architecture, compiler output,
123
+ tests, and real dependency graphs take precedence over generic path heuristics.
331
124
 
332
- - `docs/reviews/project-health-baseline.md`
333
- - `docs/reviews/optimization-backlog.md`
334
- - optional `structure.accepted_debt_paths` entries for existing large files
125
+ ## Optional documentation
335
126
 
336
- Execution evidence is written as JSONL:
127
+ Specialized templates are created only when required:
337
128
 
338
- - `docs/tasks/evidence.jsonl`
339
- - `.local/auto-coding-skill/gate-profile.jsonl`
129
+ ```bash
130
+ python3 docs/tools/autopipeline/ap.py scaffold api --write
131
+ python3 docs/tools/autopipeline/ap.py scaffold design --write
132
+ python3 docs/tools/autopipeline/ap.py scaffold architecture --write
133
+ python3 docs/tools/autopipeline/ap.py scaffold review --write
134
+ python3 docs/tools/autopipeline/ap.py scaffold testing --write
135
+ python3 docs/tools/autopipeline/ap.py scaffold deployment --write
136
+ python3 docs/tools/autopipeline/ap.py scaffold bugs --write
137
+ python3 docs/tools/autopipeline/ap.py scaffold all --write
138
+ ```
340
139
 
341
- Use `python3 docs/tools/autopipeline/ap.py gate-profile` to summarize command duration and failure history.
342
- 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.
140
+ The command is idempotent and does not overwrite existing project documents
141
+ unless `--force` is supplied. `baseline init` and `gen-summary` generate their
142
+ outputs directly without static templates.
343
143
 
344
- ## Multi-project Sync
144
+ For a one-step legacy-style full scaffold:
345
145
 
346
146
  ```bash
347
- autocoding status --projects /path/to/repo1,/path/to/repo2
348
- autocoding sync --projects /path/to/repo1,/path/to/repo2 --dry-run
349
- autocoding sync --projects /path/to/repo1,/path/to/repo2
147
+ python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install --full
350
148
  ```
351
149
 
352
- `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`.
353
-
354
- ## AGENTS.md Constraint Example
355
-
356
- ```md
357
- ## Mandatory Skill
358
- - Always use `auto-coding-skill` for implementation tasks.
359
- - Before any code change, read and obey:
360
- 1) docs/ENGINEERING.md
361
- 2) docs/architecture/structure-standard.md
362
- 3) docs/tasks/taskbook.md
363
- - Before any optimization review, also read:
364
- 1) docs/reviews/project-health-baseline.md
365
- 2) docs/reviews/optimization-backlog.md
366
- - Execute workflow commands using `python3 docs/tools/autopipeline/ap.py`.
367
- - If required docs are missing, create/update docs first, then code.
368
-
369
- ## Tooling Policy
370
- - Route by source of truth:
371
- 1) local code/tests/git -> shell + repo scripts
372
- 2) current docs/API behavior -> Context7 or matching docs skill
373
- 3) UI/browser proof -> Browser, Chrome, Playwright, or Computer Use by scenario
374
- 4) PR/Issue/CI -> GitHub connector
375
- 5) design/frontend/security/artifacts -> matching installed skill/plugin
376
- - When a connector or MCP can read or write the authoritative source directly, use it instead of retyping or duplicating state.
377
-
378
- ## Multi-Agent Policy
379
- - Use `.agents/agents` roles:
380
- 1) explorer
381
- 2) docs_researcher
382
- 3) browser_debugger
383
- 4) fixer
384
- 5) reviewer
385
- - Spawn subagents only when the client supports and allows it; otherwise run the same role phases in the main agent.
386
- - Keep one main agent responsible for task framing, integration, quality gates, docs closure, git state, and final delivery.
387
-
388
- ## Default Gate Policy
389
- - Default local gate is lightweight only.
390
- - Use `python3 docs/tools/autopipeline/ap.py classify --scope auto` to classify risk, required docs, verification surfaces, and recommended commands.
391
- - 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.
392
- - Use `python3 docs/tools/autopipeline/ap.py impact --scope auto` to inspect changed files, matched project rules, and selected gate scope.
393
- - Use `python3 docs/tools/autopipeline/ap.py structure-check --scope auto` to catch file growth, large-file extension, and missing structure baseline docs.
394
- - 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`.
395
- - Use `light-gate --scope standard` for the backward-compatible configured gate, and `light-gate --scope full` before release/deploy-sensitive closure.
396
- - The gate engine is generic. Project-specific path mapping belongs in `docs/ENGINEERING.md` under `gate.rules`; unknown or high-risk impact should upgrade to standard/full rather than silently skipping checks.
397
- - The structure gate is generic. Project-specific thresholds and accepted generated/vendor paths belong in `docs/ENGINEERING.md` under `structure.*`.
398
- - Do not require local Docker Compose or full local regression unless the task explicitly needs local runtime diagnosis.
399
- - In `dev` mode, push is the finish line after `DEV-CLOSED` is recorded.
400
- - In `verify` mode, configured CI/Jenkins success, target environment verification, and closure record are mandatory only when the corresponding `verification.*_required` switch is enabled.
401
-
402
- ## Structure Policy
403
- - Before coding, identify the right layer and reuse points.
404
- - Do not add new responsibilities to already-large files.
405
- - Prefer existing libraries, helpers, components, and scripts over new local frameworks.
406
- - Self-built concurrency/performance/tooling primitives require a reason plus tests or runtime evidence.
407
- - For optimization review, read the health baseline and backlog first; accepted debt is not a fresh blocker.
408
- ```
150
+ ## Dynamic Agents and models
409
151
 
410
- ## Docs Structure and Recording Rules
411
-
412
- ### 1) docs/ENGINEERING.md
413
- - Purpose: single source of project config + workflow rules.
414
- - How to record:
415
- - Fill YAML frontmatter once.
416
- - 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.
417
- - Target environment also includes backend server root username/password.
418
- - This file is expected to be committed to Git; prefer `*_password_env` for secrets so actual secret values stay in the current shell.
419
- - Remaining enabled environment keys are mandatory; blank values, TODO-like placeholders, and incorrect URL/path formats are treated as blocking errors by `doctor`.
420
- - 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.
421
- - Do not duplicate config elsewhere.
422
-
423
- ### 2) docs/tasks/taskbook.md
424
- - Purpose: master task ledger.
425
- - How to record:
426
- - Every task writes scope, risk, impact area, minimal design note, acceptance, evidence links.
427
- - For code changes, record structure placement, reuse check, and whether ADR is needed.
428
- - Keep this file active-only. Closed history belongs under `docs/tasks/archives/**`; an index-only file is not enough.
429
-
430
- ### 3) docs/tasks/closure-log.md
431
- - Purpose: default lightweight closure record.
432
- - How to record:
433
- - Append one record per task.
434
- - Required fields: task, commit, configured CI/Jenkins status, target env status, structure check, result, follow-up.
435
- - If CI/Jenkins failed then was fixed, also record failure reason and fix commit.
436
- - Keep this file active-only. Historical closure records belong under `docs/tasks/archives/**`.
437
-
438
- ### 4) docs/architecture/
439
- - Files:
440
- - `docs/architecture/structure-standard.md`
441
- - `docs/architecture/adr/_TEMPLATE-ADR.md`
442
- - Rule:
443
- - Read the structure standard before adding or relocating code.
444
- - Create an ADR for decisions that affect long-term structure, module boundaries, framework-like helpers, or major tradeoffs.
445
-
446
- ### 5) docs/reviews/
447
- - Files:
448
- - `docs/reviews/project-health-baseline.md`
449
- - `docs/reviews/optimization-backlog.md`
450
- - Rule:
451
- - Structure and optimization reviews must read these before listing findings.
452
- - Accepted debt is not a fresh blocker unless it worsened or needs priority upgrade.
453
-
454
- ### 6) docs/design/
455
- - Purpose: DD for cross-module / API / DB / deployment / CI/Jenkins / key-page-flow changes.
456
- - How to record:
457
- - Small changes do not need a standalone DD file.
458
- - Higher-risk changes create `docs/design/<TASK_ID>-<slug>.md`.
459
- - Keep top-level `docs/design/T*.md` active-only. Historical DDs belong under `docs/archive/design/**`.
460
-
461
- ### 6.5) docs/tasks/archives/ and docs/archive/design/
462
- - Purpose: physical history archives for closed taskbook entries, closure records, and old DDs.
463
- - Rule:
464
- - Archive by period or legacy bucket when active ledgers exceed `docs.active_*` budgets.
465
- - `docs/tasks/archive-index.md` may summarize and link archives, but it is not the archive itself.
466
- - `doctor` blocks over-budget active ledgers when `docs.ledger_block_on_exceed: true`.
467
-
468
- ### 7) docs/interfaces/
469
- - Files:
470
- - `docs/interfaces/api.md`
471
- - `docs/interfaces/api-change-log.md`
472
- - Rule:
473
- - Any API change updates both files in the same task.
474
-
475
- ### 8) docs/testing/regression-matrix.md
476
- - Purpose: on-demand regression evidence, not default gate for every small change.
477
- - Rule:
478
- - Only real executed items can be marked `PASS`.
479
- - `check-matrix` is used only when full regression is explicitly required.
480
-
481
- ### 9) docs/tasks/summaries/
482
- - Purpose: optional long-form summary.
483
- - Rule:
484
- - Only for high-risk changes, milestones, or tasks that need full retrospective.
485
-
486
- ### 8) docs/deployment/
487
- - Purpose: optional heavy deployment audit docs.
488
- - Rule:
489
- - Only for manual deploys, high-risk releases, or explicit audit requirements.
490
-
491
- ## High-risk Changes
492
-
493
- These categories require stronger verification and usually a DD:
494
- - Database migration
495
- - Authentication / authorization
496
- - Payment / order
497
- - Deployment / CI / Jenkins
498
- - Nginx / gateway
499
- - File upload / download
500
- - Production configuration
501
-
502
- For these tasks, use `workflow.mode: "verify"` or run an explicit verification pass after the fast `dev` closure.
503
-
504
- ## Commands
505
-
506
- Recommended default flow:
152
+ Managed role templates define role instructions, permissions, and reasoning
153
+ effort but do not pin a model. The current client therefore supplies a supported
154
+ model automatically.
507
155
 
508
- ```bash
509
- pip install pyyaml requests
510
- python3 docs/tools/autopipeline/ap.py doctor
511
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
512
- ```
156
+ Existing project-local `model = "..."` lines are treated as explicit overrides:
513
157
 
514
- Development mode can also be forced per run:
158
+ - `status` reports them but does not mark the project stale for model-only drift.
159
+ - `sync` updates managed instructions while preserving the override.
160
+ - `sync --reset-agent-models` removes managed-role overrides and returns to
161
+ client inheritance.
162
+ - Custom Agent files are always preserved byte-for-byte.
515
163
 
516
- ```bash
517
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode dev --msg "<TASK_ID>: <summary>"
518
- ```
164
+ The effective profile recommends roles dynamically:
519
165
 
520
- Verification mode runs the configured CI/Jenkins + target-environment loop. Disabled surfaces are recorded as skipped:
166
+ - micro: main Agent only by default
167
+ - standard: explorer → fixer, plus browser/docs roles when indicated
168
+ - high-risk: explorer/docs as indicated → fixer → browser as indicated → reviewer
521
169
 
522
- ```bash
523
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> \
524
- --mode verify \
525
- --msg "<TASK_ID>: <summary>" \
526
- --backend-path /health \
527
- --frontend-path /
528
- ```
170
+ ## Verification configuration
529
171
 
530
- Manual verification commands remain available:
172
+ Generic projects start with both optional external surfaces disabled:
531
173
 
532
- ```bash
533
- python3 docs/tools/autopipeline/ap.py verify-jenkins-build --git-ref HEAD
534
- python3 docs/tools/autopipeline/ap.py wait-health --scope target
535
- python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
536
- 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"
174
+ ```yaml
175
+ verification:
176
+ target_env_required: false
177
+ jenkins_required: false
537
178
  ```
538
179
 
539
- Available on-demand commands:
180
+ When target verification is enabled, `doctor` requires only the health URL/path
181
+ needed by the default health check. Frontend/backend URLs and credentials are
182
+ validated when the corresponding path or basic-auth options are actually used.
183
+ Jenkins keeps its explicit configuration checks. Unused sections should stay
184
+ absent rather than containing placeholders.
185
+
186
+ ## Core commands
540
187
 
541
188
  ```bash
542
189
  python3 docs/tools/autopipeline/ap.py doctor
190
+ python3 docs/tools/autopipeline/ap.py classify --scope auto
191
+ python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
192
+ python3 docs/tools/autopipeline/ap.py structure-check --scope auto
543
193
  python3 docs/tools/autopipeline/ap.py docs-ledger-check
544
- python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
545
- python3 docs/tools/autopipeline/ap.py verify-api-docs
546
- python3 docs/tools/autopipeline/ap.py verify-jenkins
547
- python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
548
- python3 docs/tools/autopipeline/ap.py verify-jenkins-build --job-name <job-name> --build-number <number>
549
- python3 docs/tools/autopipeline/ap.py verify-jenkins-build --job-url <job-url> --build-number <number>
550
- python3 docs/tools/autopipeline/ap.py verify-jenkins-build --multibranch-root-job <root-job> --branch-name <branch> --build-number <number>
551
- python3 docs/tools/autopipeline/ap.py runtime-up
552
- python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
553
- python3 docs/tools/autopipeline/ap.py runtime-down
554
- python3 docs/tools/autopipeline/ap.py check-matrix
555
- python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
194
+ python3 docs/tools/autopipeline/ap.py gate-profile
195
+ python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
556
196
  ```
557
197
 
558
- ## Optional Jenkins Build Tracking
198
+ ## Upgrade and multi-project sync
559
199
 
560
- - `verify-jenkins-build --git-ref HEAD`
561
- - Use when Jenkins build descriptions include commit SHA and you want to find the latest build automatically.
562
- - `verify-jenkins-build --job-name <folder/job> --build-number <N>`
563
- - Use when you already know the Jenkins job and build number.
564
- - `verify-jenkins-build --job-url <full-job-url> --build-number <N>`
565
- - Use when you want to bypass configured job resolution.
566
- - `verify-jenkins-build --multibranch-root-job <folder/repo> --branch-name <branch> --build-number <N>`
567
- - Use for multibranch or organization-folder jobs where the branch is a child job.
568
- - `verify-jenkins-build --multibranch-root-job <folder/repo> --git-ref HEAD`
569
- - Use when the current Git branch should be inferred automatically.
570
- - If Jenkins returns `403`, the script retries with crumb / CSRF handling automatically.
200
+ ```bash
201
+ autocoding sync --projects /path/a,/path/b
571
202
 
572
- ## New Safeguards
203
+ python3 docs/tools/autopipeline/ap.py upgrade --dry-run
204
+ python3 docs/tools/autopipeline/ap.py upgrade --write
573
205
 
574
- - `doctor`
575
- - Checks whether the default lightweight workflow is actually configured instead of silently skipping gates.
576
- - `light-gate`
577
- - Now prefers one curated fast gate command instead of serially running every expensive check.
578
- - `verify-target`
579
- - Performs real target-environment verification beyond health checks when you provide key backend/frontend paths.
580
- - `commit-push --record-closure`
581
- - Kept for compatibility; normal `commit-push` now records closure automatically based on `workflow.mode`.
206
+ autocoding status --projects /path/a,/path/b
207
+ autocoding sync --projects /path/a,/path/b --dry-run
208
+ ```
582
209
 
583
- ## Publish (NPM)
210
+ For a v2.1 project, run the new CLI sync first; invoking its old project-local
211
+ `upgrade` command would still execute v2.1 logic. Upgrade and sync preserve
212
+ existing optional docs, legacy `core.py` /
213
+ `http_checks.py` tool copies, custom Agents, and project-specific configuration.
214
+ Retired template files do not count as drift.
584
215
 
585
- 1. Sync assets and basic check:
216
+ ## Development
586
217
 
587
218
  ```bash
588
219
  npm run sync-assets
220
+ npm run check:assets
221
+ npm run test:src
589
222
  npm test
590
- ```
591
-
592
- 2. Bump version:
593
-
594
- ```bash
595
- npm version patch
596
- # or: npm version minor / major
597
- ```
598
-
599
- 3. Release check:
600
-
601
- ```bash
602
- npm whoami
603
223
  npm run release:check
604
224
  ```
605
225
 
606
- 4. Publish:
607
-
608
- ```bash
609
- npm publish --access public
610
- # or
611
- npm publish --access public --otp <6-digit-otp>
612
- ```
613
-
614
- 5. Verify and update:
615
-
616
- ```bash
617
- npm view @elvis1513/auto-coding-skill version
618
- npm install -g @elvis1513/auto-coding-skill@latest
619
- ```
620
-
621
- ## License
226
+ `release:check` synchronizes source assets, validates Python 3.11 grammar and
227
+ TOML, runs installer and profile regressions, and performs `npm pack --dry-run`.
622
228
 
623
- MIT
229
+ License: MIT.