@elvis1513/auto-coding-skill 2.1.4 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +163 -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 +703 -138
  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 +376 -87
  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,238 @@
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.1
8
+
9
+ - Made same-period ledger archiving update one cumulative archive-index entry
10
+ instead of appending duplicate month headings.
11
+ - Recognized Markdown-wrapped and localized settled statuses such as
12
+ `` `Done / PASS` `` and `Done(PASS)` during physical history archiving.
13
+ - Added regression coverage for repeated same-month archives and these status
14
+ formats.
15
+
16
+ ## What changed in v2.2.0
17
+
18
+ - Added `micro`, `standard`, and `high-risk` execution profiles.
19
+ - `workflow.profile: auto` classifies changed work and cannot downgrade detected
20
+ high-risk changes.
21
+ - High-risk and explicit verify work now require a real `gate_full`/`full_gate`;
22
+ light and standard commands are no longer accepted as full-gate fallbacks.
23
+ - Generic structure checks are advisory by default. Projects can opt into
24
+ blocking enforcement.
25
+ - Reduced a new project scaffold from 46 files / about 10,120 lines to 20 files /
26
+ about 5,300 lines.
27
+ - Replaced duplicated repository-side Python tools with a small launcher that
28
+ delegates to the single project-local skill runtime.
29
+ - Kept only ENGINEERING, taskbook, and closure log in the default documentation
30
+ scaffold; all specialized documents are materialized on demand.
31
+ - Removed hard-coded model names from managed Agent templates. New installs
32
+ inherit the active client model; existing project model overrides survive sync.
33
+ - Added behavioral regression tests for profile resolution, strict full gates,
34
+ advisory structure checks, minimal scaffold budgets, on-demand docs, and Agent
35
+ model inheritance.
10
36
 
11
37
  ## Install
12
38
 
13
39
  ```bash
14
40
  npm install -g @elvis1513/auto-coding-skill
41
+ autocoding init
42
+ autocoding sync --projects .
43
+ pip install pyyaml requests
15
44
  ```
16
45
 
17
- Fallback:
46
+ `autocoding init` installs the project-local skill and five managed roles under
47
+ `.agents`. `autocoding sync` installs the minimal project scaffold:
18
48
 
19
- ```bash
20
- npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
49
+ ```text
50
+ .agents/skills/auto-coding-skill/
51
+ .agents/agents/
52
+ docs/ENGINEERING.md
53
+ docs/tasks/taskbook.md
54
+ docs/tasks/closure-log.md
55
+ docs/tools/autopipeline/ap.py
21
56
  ```
22
57
 
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
58
+ The `docs/tools` entry point is a compatibility launcher. Runtime code lives only
59
+ under `.agents/skills/auto-coding-skill/scripts`.
97
60
 
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.
61
+ ## Execution profiles
104
62
 
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` 顶部控制:
63
+ Configure the selector in `docs/ENGINEERING.md`:
126
64
 
127
65
  ```yaml
128
66
  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
67
+ mode: dev
68
+ profile: auto
192
69
  ```
193
70
 
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.
71
+ | Effective profile | Intended work | Gate scope | Mode |
72
+ | --- | --- | --- | --- |
73
+ | `micro` | docs/tests-only or explicitly isolated work | changed | dev |
74
+ | `standard` | normal feature and defect work | standard | dev |
75
+ | `high-risk` | DB/auth/payment/file transfer/gateway/prod/deploy/build changes | full | verify |
197
76
 
198
- 2. Initialize docs and local scripts:
77
+ `auto` is a selector, not a fourth effective profile. Full-path patterns,
78
+ high-risk categories, `gate.rules[].profile: high-risk`, and explicit verify work
79
+ raise the plan to `high-risk`. A CLI `--profile micro` or `--mode dev` cannot
80
+ lower it.
199
81
 
200
- ```bash
201
- python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install
202
- ```
82
+ An explicit configured `micro`, `standard`, or `high-risk` profile replaces
83
+ auto's low/normal baseline and acts as a floor for CLI overrides. Independently
84
+ detected high-risk signals still force `high-risk`.
203
85
 
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:
86
+ Inspect the plan:
294
87
 
295
88
  ```bash
296
89
  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
90
+ python3 docs/tools/autopipeline/ap.py impact --scope auto --json
305
91
  ```
306
92
 
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.
93
+ Each result includes the effective profile, mode, gate scope, reasons, required
94
+ verification surfaces, and recommended Agent roles.
314
95
 
315
- ## Project Upgrade
96
+ ## Gate configuration
316
97
 
317
- For existing projects, do not rerun initialization blindly. Use:
98
+ ```yaml
99
+ commands:
100
+ gate_changed: "npm run test:changed"
101
+ gate_standard: "npm test"
102
+ gate_full: "npm run test:full"
318
103
 
319
- ```bash
320
- python3 docs/tools/autopipeline/ap.py upgrade --dry-run
321
- python3 docs/tools/autopipeline/ap.py upgrade --write
104
+ gate:
105
+ default_scope: auto
106
+ rules:
107
+ - name: payments
108
+ paths: ["src/payments/**"]
109
+ profile: high-risk
322
110
  ```
323
111
 
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.
112
+ For Node projects, a new scaffold can infer changed/standard commands from
113
+ `test`, `test:changed`, and `test:standard`. It only infers a full command from a
114
+ dedicated `test:full` script; ordinary `npm test` is never promoted to full.
115
+ A high-risk or verify run fails clearly when no real full command is configured.
327
116
 
328
- ## Baseline And Evidence
117
+ ## Structure policy
329
118
 
330
- Initialize a project health baseline:
119
+ The generic checker remains useful for surfacing large files, large additions,
120
+ function-size signals, and import-direction heuristics, but it is not universally
121
+ authoritative:
331
122
 
332
- ```bash
333
- python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
123
+ ```yaml
124
+ structure:
125
+ enabled: true
126
+ enforcement: advisory # advisory | blocking
127
+ architecture_standard: project-defined
334
128
  ```
335
129
 
336
- This creates:
130
+ `advisory` reports findings without blocking. Projects with reliable, tailored
131
+ rules can opt into `blocking`. Repository-native architecture, compiler output,
132
+ tests, and real dependency graphs take precedence over generic path heuristics.
337
133
 
338
- - `docs/reviews/project-health-baseline.md`
339
- - `docs/reviews/optimization-backlog.md`
340
- - optional `structure.accepted_debt_paths` entries for existing large files
134
+ ## Optional documentation
341
135
 
342
- Execution evidence is written as JSONL:
136
+ Specialized templates are created only when required:
343
137
 
344
- - `docs/tasks/evidence.jsonl`
345
- - `.local/auto-coding-skill/gate-profile.jsonl`
138
+ ```bash
139
+ python3 docs/tools/autopipeline/ap.py scaffold api --write
140
+ python3 docs/tools/autopipeline/ap.py scaffold design --write
141
+ python3 docs/tools/autopipeline/ap.py scaffold architecture --write
142
+ python3 docs/tools/autopipeline/ap.py scaffold review --write
143
+ python3 docs/tools/autopipeline/ap.py scaffold testing --write
144
+ python3 docs/tools/autopipeline/ap.py scaffold deployment --write
145
+ python3 docs/tools/autopipeline/ap.py scaffold bugs --write
146
+ python3 docs/tools/autopipeline/ap.py scaffold all --write
147
+ ```
346
148
 
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.
149
+ The command is idempotent and does not overwrite existing project documents
150
+ unless `--force` is supplied. `baseline init` and `gen-summary` generate their
151
+ outputs directly without static templates.
349
152
 
350
- ## Multi-project Sync
153
+ For a one-step legacy-style full scaffold:
351
154
 
352
155
  ```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
156
+ python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install --full
356
157
  ```
357
158
 
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
- ```
159
+ ## Dynamic Agents and models
415
160
 
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:
161
+ Managed role templates define role instructions, permissions, and reasoning
162
+ effort but do not pin a model. The current client therefore supplies a supported
163
+ model automatically.
513
164
 
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
- ```
165
+ Existing project-local `model = "..."` lines are treated as explicit overrides:
519
166
 
520
- Development mode can also be forced per run:
167
+ - `status` reports them but does not mark the project stale for model-only drift.
168
+ - `sync` updates managed instructions while preserving the override.
169
+ - `sync --reset-agent-models` removes managed-role overrides and returns to
170
+ client inheritance.
171
+ - Custom Agent files are always preserved byte-for-byte.
521
172
 
522
- ```bash
523
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode dev --msg "<TASK_ID>: <summary>"
524
- ```
173
+ The effective profile recommends roles dynamically:
525
174
 
526
- Verification mode runs the configured CI/Jenkins + target-environment loop. Disabled surfaces are recorded as skipped:
175
+ - micro: main Agent only by default
176
+ - standard: explorer → fixer, plus browser/docs roles when indicated
177
+ - high-risk: explorer/docs as indicated → fixer → browser as indicated → reviewer
527
178
 
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
- ```
179
+ ## Verification configuration
535
180
 
536
- Manual verification commands remain available:
181
+ Generic projects start with both optional external surfaces disabled:
537
182
 
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"
183
+ ```yaml
184
+ verification:
185
+ target_env_required: false
186
+ jenkins_required: false
543
187
  ```
544
188
 
545
- Available on-demand commands:
189
+ When target verification is enabled, `doctor` requires only the health URL/path
190
+ needed by the default health check. Frontend/backend URLs and credentials are
191
+ validated when the corresponding path or basic-auth options are actually used.
192
+ Jenkins keeps its explicit configuration checks. Unused sections should stay
193
+ absent rather than containing placeholders.
194
+
195
+ ## Core commands
546
196
 
547
197
  ```bash
548
198
  python3 docs/tools/autopipeline/ap.py doctor
199
+ python3 docs/tools/autopipeline/ap.py classify --scope auto
200
+ python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
201
+ python3 docs/tools/autopipeline/ap.py structure-check --scope auto
549
202
  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>
203
+ python3 docs/tools/autopipeline/ap.py gate-profile
204
+ python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
562
205
  ```
563
206
 
564
- ## Optional Jenkins Build Tracking
207
+ ## Upgrade and multi-project sync
565
208
 
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.
209
+ ```bash
210
+ autocoding sync --projects /path/a,/path/b
577
211
 
578
- ## New Safeguards
212
+ python3 docs/tools/autopipeline/ap.py upgrade --dry-run
213
+ python3 docs/tools/autopipeline/ap.py upgrade --write
579
214
 
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`.
215
+ autocoding status --projects /path/a,/path/b
216
+ autocoding sync --projects /path/a,/path/b --dry-run
217
+ ```
588
218
 
589
- ## Publish (NPM)
219
+ For a v2.1 project, run the new CLI sync first; invoking its old project-local
220
+ `upgrade` command would still execute v2.1 logic. Upgrade and sync preserve
221
+ existing optional docs, legacy `core.py` /
222
+ `http_checks.py` tool copies, custom Agents, and project-specific configuration.
223
+ Retired template files do not count as drift.
590
224
 
591
- 1. Sync assets and basic check:
225
+ ## Development
592
226
 
593
227
  ```bash
594
228
  npm run sync-assets
229
+ npm run check:assets
230
+ npm run test:src
595
231
  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
232
  npm run release:check
610
233
  ```
611
234
 
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
235
+ `release:check` synchronizes source assets, validates Python 3.11 grammar and
236
+ TOML, runs installer and profile regressions, and performs `npm pack --dry-run`.
628
237
 
629
- MIT
238
+ License: MIT.