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