@elvis1513/auto-coding-skill 2.0.6 → 2.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +144 -34
- package/cli/assets/agents/explorer.toml +8 -6
- package/cli/assets/agents/fixer.toml +8 -7
- package/cli/assets/agents/reviewer.toml +8 -6
- package/cli/assets/skill/SKILL.md +70 -29
- package/cli/assets/skill/data/templates/ENGINEERING.md +134 -36
- package/cli/assets/skill/data/templates/bridges/{CLAUDE.md → AGENTS.md} +6 -2
- package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +24 -0
- package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +1 -1
- package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +1 -1
- package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +6 -4
- package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +1 -0
- package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +4 -1
- package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +7 -6
- package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +4 -2
- package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +7 -6
- package/cli/assets/skill/scripts/ap.py +1589 -77
- package/cli/src/index.js +303 -53
- package/cli/tests/index.test.js +146 -0
- package/package.json +7 -7
- package/cli/assets/skill/data/templates/bridges/CODEX.md +0 -8
package/README.md
CHANGED
|
@@ -2,12 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
Engineering workflow skill for:
|
|
4
4
|
|
|
5
|
-
-
|
|
6
|
-
- Codex CLI
|
|
5
|
+
- shared `.agents` skills and role templates
|
|
7
6
|
|
|
8
|
-
This skill targets
|
|
7
|
+
This skill targets general software projects that need a disciplined task -> design -> implementation -> verification -> closure workflow. The default `dev` mode is optimized for fast development: light gate, early closure record, commit, push, then move to the next task. Switch to `verify` mode when configured CI/Jenkins and target-environment evidence must be completed before closure.
|
|
9
8
|
|
|
10
|
-
`docs/ENGINEERING.md` is intentionally Git-tracked.
|
|
9
|
+
`docs/ENGINEERING.md` is intentionally Git-tracked. Environment fields kept in that file are mandatory only when their verification surface is enabled. Unused environment items should be removed instead of being kept as placeholders.
|
|
11
10
|
|
|
12
11
|
## Install
|
|
13
12
|
|
|
@@ -23,6 +22,40 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
|
|
|
23
22
|
|
|
24
23
|
## Release Notes
|
|
25
24
|
|
|
25
|
+
### v2.1.1
|
|
26
|
+
|
|
27
|
+
- Removed client-specific init targets from the npm CLI; installs now target the shared `.agents` layout only.
|
|
28
|
+
- `ap.py install --bridges` now creates a generic `AGENTS.md` bridge instead of client-named bridge files.
|
|
29
|
+
- `autocoding init --force` now preserves custom files in `.agents/agents`; only managed template files are refreshed.
|
|
30
|
+
- `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`.
|
|
31
|
+
- `autocoding sync` now creates a missing `docs/ENGINEERING.md` from the template, while still preserving existing project-specific config.
|
|
32
|
+
- `autocoding init` now preflights both skill and agent targets before writing files, preventing partial installs when one target already exists.
|
|
33
|
+
- Added CLI installer regression tests for dest variants, partial-init failure, sync convergence, bridge generation, custom-agent preservation, and managed bridge cleanup.
|
|
34
|
+
- Made `npm test` runnable from the published package by testing packaged assets separately from source-tree asset synchronization checks.
|
|
35
|
+
- `autocoding status/sync` now treats `.agents/agents` as a shared directory: managed templates are checked and refreshed, while project-specific custom agents are preserved.
|
|
36
|
+
- Added `install --force` protection: plain `ap.py install` now refuses to overwrite existing generated docs/tooling and directs existing projects to `upgrade`.
|
|
37
|
+
- 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.
|
|
38
|
+
- Added generic `--ci-build` / `--ci-failure` aliases for closure commands while keeping legacy Jenkins flags compatible.
|
|
39
|
+
- Added `ap.py docs-ledger-check` to prevent documentation ledgers from growing without a real archive.
|
|
40
|
+
- 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.
|
|
41
|
+
- `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.
|
|
42
|
+
- `doctor` records a standalone `docs_ledger_check` evidence event with counts and blocking details.
|
|
43
|
+
- `docs-ledger-check` now fails on missing active ledger files instead of treating them as empty ledgers.
|
|
44
|
+
- `autocoding status` now parses `docs/ENGINEERING.md` frontmatter key paths instead of matching config tokens in prose.
|
|
45
|
+
- Added `verification.target_env_required` and `verification.jenkins_required` so non-Jenkins or local-only projects can keep `doctor` generic.
|
|
46
|
+
- Added `docs.task_archive_dir`, `docs.design_archive_dir`, `docs.archive_index`, and active ledger budget settings to `docs/ENGINEERING.md`.
|
|
47
|
+
- Clarified that `archive-index.md` is only navigation; it does not replace monthly or legacy physical archives.
|
|
48
|
+
|
|
49
|
+
### v2.1.0
|
|
50
|
+
|
|
51
|
+
- Added project upgrade support: `ap.py upgrade --dry-run|--write` safely syncs tooling and merges missing `docs/ENGINEERING.md` keys without overwriting existing values.
|
|
52
|
+
- 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`.
|
|
53
|
+
- Added configurable structure import-boundary checks through `structure.layer_rules`.
|
|
54
|
+
- Added local gate profiling: configured gate commands write `.local/auto-coding-skill/gate-profile.jsonl`, summarized by `ap.py gate-profile`.
|
|
55
|
+
- Added multi-project npm CLI operations: `autocoding status --projects ...` and `autocoding sync --projects ...`.
|
|
56
|
+
- Added structured evidence logging to `docs/tasks/evidence.jsonl` for classify, doctor, structure-check, gates, verification, and closure.
|
|
57
|
+
- Added task classification: `ap.py classify --scope auto` reports risk, categories, required DD/ADR/browser/Jenkins/target checks, and recommended commands.
|
|
58
|
+
|
|
26
59
|
### v2.0.6
|
|
27
60
|
|
|
28
61
|
- Fixed `structure-check --json` so successful output stays machine-readable JSON without a trailing OK line.
|
|
@@ -51,16 +84,16 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
|
|
|
51
84
|
|
|
52
85
|
### v2.0.2
|
|
53
86
|
|
|
54
|
-
- Added default
|
|
55
|
-
- `autocoding init
|
|
56
|
-
- Updated
|
|
87
|
+
- Added default subagent templates under `.agents/agents`.
|
|
88
|
+
- `autocoding init` installs the managed agent templates automatically.
|
|
89
|
+
- Updated agent defaults to current model names: `gpt-5.5`, `gpt-5.4-mini`, and `gpt-5.3-codex-spark`; highest reasoning uses `xhigh`.
|
|
57
90
|
- Added concrete capability routing for MCP servers, installed skills, plugins/apps/connectors, browser tools, GitHub, Figma, security review, and artifact workflows.
|
|
58
91
|
- Changed multi-agent guidance from unconditional delegation to a role model that works either as real subagents or as sequential main-agent phases.
|
|
59
92
|
- Hardened CLI help/argument validation, asset sync checks, and stricter autopipeline config diagnostics.
|
|
60
93
|
|
|
61
94
|
### v2.0.1
|
|
62
95
|
|
|
63
|
-
- Updated the
|
|
96
|
+
- Updated the installer target to `.agents/skills`, matching current global and project skill discovery.
|
|
64
97
|
|
|
65
98
|
### v0.3.1
|
|
66
99
|
|
|
@@ -91,15 +124,15 @@ workflow:
|
|
|
91
124
|
|
|
92
125
|
`verify` 完整闭环:
|
|
93
126
|
|
|
94
|
-
`需求/任务记录 -> 最小设计 -> 开发 -> 本地轻量校验 -> commit/push -> Jenkins
|
|
127
|
+
`需求/任务记录 -> 最小设计 -> 开发 -> 本地轻量校验 -> commit/push -> 已启用的 CI/Jenkins 验证 -> 已启用的目标环境验证 -> 写 PASS 闭环`
|
|
95
128
|
|
|
96
129
|
具体执行顺序:
|
|
97
130
|
|
|
98
131
|
1. 需求确认
|
|
99
|
-
- 明确任务范围、影响服务、是否涉及 API / 数据库 / 部署 / Jenkins / 前端页面。
|
|
132
|
+
- 明确任务范围、影响服务、是否涉及 API / 数据库 / 部署 / CI/Jenkins / 前端页面。
|
|
100
133
|
2. 最小设计记录
|
|
101
134
|
- 普通小改动只更新 `taskbook` 或相关设计文档的一小段。
|
|
102
|
-
- 跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD。
|
|
135
|
+
- 跨模块、接口、数据库、部署、CI/Jenkins、关键页面流程变更才补 DD。
|
|
103
136
|
3. 开发实现
|
|
104
137
|
- 只修改本次任务必要文件,不做无关重构。
|
|
105
138
|
4. 本地轻量校验
|
|
@@ -107,18 +140,18 @@ workflow:
|
|
|
107
140
|
- 若未配置,再执行 quick test / test / build 中最先配置的一项
|
|
108
141
|
- `git diff --check`
|
|
109
142
|
- API 文档检查
|
|
110
|
-
- Jenkins 配置检查
|
|
143
|
+
- 已启用的 CI/Jenkins 配置检查
|
|
111
144
|
5. 提交推送
|
|
112
|
-
- `dev` 模式:轻量校验通过后,先写 `DEV-CLOSED` 闭环,再 commit + push
|
|
113
|
-
- `verify` 模式:commit + push
|
|
114
|
-
6. Jenkins 验证
|
|
115
|
-
- 仅 `verify`
|
|
145
|
+
- `dev` 模式:轻量校验通过后,先写 `DEV-CLOSED` 闭环,再 commit + push 后结束。
|
|
146
|
+
- `verify` 模式:commit + push 后继续等待已启用的 CI/Jenkins 和目标环境验证。
|
|
147
|
+
6. CI/Jenkins 验证
|
|
148
|
+
- 仅 `verify` 模式且 `verification.jenkins_required: true` 时默认执行。看 CI/Jenkins 构建、镜像、部署结果;失败则基于日志修复并再次提交。
|
|
116
149
|
7. 目标环境验证
|
|
117
|
-
- 仅 `verify`
|
|
150
|
+
- 仅 `verify` 模式且 `verification.target_env_required: true` 时默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
|
|
118
151
|
8. 回归与证据记录
|
|
119
|
-
-
|
|
152
|
+
- 只有真实执行过已启用的 CI/Jenkins / 目标环境验证,或明确要求本地运行验证时,才把 regression matrix 写成 `PASS`。
|
|
120
153
|
9. 闭环记录
|
|
121
|
-
- `dev` 模式记录 `DEV-CLOSED`,表示开发闭环完成但 Jenkins/目标环境未验证。
|
|
154
|
+
- `dev` 模式记录 `DEV-CLOSED`,表示开发闭环完成但 CI/Jenkins/目标环境未验证。
|
|
122
155
|
- `verify` 模式记录 `PASS` / `FAIL` / `PARTIAL`,必须基于真实验证结果。
|
|
123
156
|
|
|
124
157
|
## Default vs On-demand
|
|
@@ -144,20 +177,21 @@ workflow:
|
|
|
144
177
|
1. Install skill into project:
|
|
145
178
|
|
|
146
179
|
```bash
|
|
147
|
-
autocoding init
|
|
148
|
-
# or: --ai codex / --ai claude
|
|
180
|
+
autocoding init
|
|
149
181
|
```
|
|
150
182
|
|
|
151
|
-
|
|
183
|
+
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`.
|
|
184
|
+
|
|
185
|
+
For non-current-directory installs, `--dest` accepts a repo root, a `.agents` directory, `.agents/skills`, or the direct `.agents/skills/auto-coding-skill` directory.
|
|
152
186
|
|
|
153
187
|
2. Initialize docs and local scripts:
|
|
154
188
|
|
|
155
189
|
```bash
|
|
156
190
|
python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install
|
|
157
|
-
# or
|
|
158
|
-
python3 .claude/skills/auto-coding-skill/scripts/ap.py --repo . install
|
|
159
191
|
```
|
|
160
192
|
|
|
193
|
+
`install` refuses to overwrite existing generated docs/tooling unless `--force` is passed. For existing projects, use `upgrade` instead of rerunning initialization blindly.
|
|
194
|
+
|
|
161
195
|
3. Fill only one file manually:
|
|
162
196
|
|
|
163
197
|
- `docs/ENGINEERING.md` frontmatter
|
|
@@ -171,6 +205,7 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
171
205
|
- `gate.*`
|
|
172
206
|
- `structure.*`
|
|
173
207
|
- `optimization.*`
|
|
208
|
+
- `verification.*`
|
|
174
209
|
- `target_env.*`
|
|
175
210
|
- `jenkins.*`
|
|
176
211
|
- `docs.*`
|
|
@@ -179,6 +214,10 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
179
214
|
- `workflow.mode`
|
|
180
215
|
- `project.name`
|
|
181
216
|
- `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`,或 `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
|
|
217
|
+
- `verification.target_env_required`
|
|
218
|
+
- `verification.jenkins_required`
|
|
219
|
+
|
|
220
|
+
仅当 `verification.target_env_required: true` 时必填:
|
|
182
221
|
- `target_env.name`
|
|
183
222
|
- `target_env.frontend_base_url`
|
|
184
223
|
- `target_env.frontend_username`
|
|
@@ -190,6 +229,8 @@ It must be committed to Git. Do not add it to `.gitignore`.
|
|
|
190
229
|
- `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
|
|
191
230
|
- `target_env.health_base_url`
|
|
192
231
|
- `target_env.health_path`
|
|
232
|
+
|
|
233
|
+
仅当 `verification.jenkins_required: true` 时必填:
|
|
193
234
|
- `jenkins.base_url`
|
|
194
235
|
- `jenkins.ui_username`
|
|
195
236
|
- `jenkins.ui_password` 或 `jenkins.ui_password_env`
|
|
@@ -241,14 +282,69 @@ The default project scaffold includes a generic professional structure standard:
|
|
|
241
282
|
Useful commands:
|
|
242
283
|
|
|
243
284
|
```bash
|
|
285
|
+
python3 docs/tools/autopipeline/ap.py classify --scope auto
|
|
286
|
+
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
287
|
+
python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
|
|
244
288
|
python3 docs/tools/autopipeline/ap.py structure-check --scope auto
|
|
245
289
|
python3 docs/tools/autopipeline/ap.py structure-check --scope full
|
|
246
290
|
python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
|
|
291
|
+
python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
|
|
292
|
+
python3 docs/tools/autopipeline/ap.py gate-profile
|
|
293
|
+
python3 docs/tools/autopipeline/ap.py upgrade --dry-run
|
|
247
294
|
```
|
|
248
295
|
|
|
249
296
|
`structure-check` is intentionally generic. Project-specific paths and stricter rules belong in `docs/ENGINEERING.md` under `structure.*`, `optimization.*`, and optional `commands.structure_check`.
|
|
250
297
|
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.
|
|
251
298
|
|
|
299
|
+
`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.
|
|
300
|
+
|
|
301
|
+
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.
|
|
302
|
+
|
|
303
|
+
## Project Upgrade
|
|
304
|
+
|
|
305
|
+
For existing projects, do not rerun initialization blindly. Use:
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
python3 docs/tools/autopipeline/ap.py upgrade --dry-run
|
|
309
|
+
python3 docs/tools/autopipeline/ap.py upgrade --write
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
`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`.
|
|
313
|
+
|
|
314
|
+
Use `install --force` only when intentionally resetting generated docs/tooling.
|
|
315
|
+
|
|
316
|
+
## Baseline And Evidence
|
|
317
|
+
|
|
318
|
+
Initialize a project health baseline:
|
|
319
|
+
|
|
320
|
+
```bash
|
|
321
|
+
python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
This creates:
|
|
325
|
+
|
|
326
|
+
- `docs/reviews/project-health-baseline.md`
|
|
327
|
+
- `docs/reviews/optimization-backlog.md`
|
|
328
|
+
- optional `structure.accepted_debt_paths` entries for existing large files
|
|
329
|
+
|
|
330
|
+
Execution evidence is written as JSONL:
|
|
331
|
+
|
|
332
|
+
- `docs/tasks/evidence.jsonl`
|
|
333
|
+
- `.local/auto-coding-skill/gate-profile.jsonl`
|
|
334
|
+
|
|
335
|
+
Use `python3 docs/tools/autopipeline/ap.py gate-profile` to summarize command duration and failure history.
|
|
336
|
+
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.
|
|
337
|
+
|
|
338
|
+
## Multi-project Sync
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
autocoding status --projects /path/to/repo1,/path/to/repo2
|
|
342
|
+
autocoding sync --projects /path/to/repo1,/path/to/repo2 --dry-run
|
|
343
|
+
autocoding sync --projects /path/to/repo1,/path/to/repo2
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
`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`.
|
|
347
|
+
|
|
252
348
|
## AGENTS.md Constraint Example
|
|
253
349
|
|
|
254
350
|
```md
|
|
@@ -285,6 +381,8 @@ Historical large-file debt can be listed in `structure.accepted_debt_paths` afte
|
|
|
285
381
|
|
|
286
382
|
## Default Gate Policy
|
|
287
383
|
- Default local gate is lightweight only.
|
|
384
|
+
- Use `python3 docs/tools/autopipeline/ap.py classify --scope auto` to classify risk, required docs, verification surfaces, and recommended commands.
|
|
385
|
+
- 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.
|
|
288
386
|
- Use `python3 docs/tools/autopipeline/ap.py impact --scope auto` to inspect changed files, matched project rules, and selected gate scope.
|
|
289
387
|
- Use `python3 docs/tools/autopipeline/ap.py structure-check --scope auto` to catch file growth, large-file extension, and missing structure baseline docs.
|
|
290
388
|
- 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`.
|
|
@@ -293,7 +391,7 @@ Historical large-file debt can be listed in `structure.accepted_debt_paths` afte
|
|
|
293
391
|
- The structure gate is generic. Project-specific thresholds and accepted generated/vendor paths belong in `docs/ENGINEERING.md` under `structure.*`.
|
|
294
392
|
- Do not require local Docker Compose or full local regression unless the task explicitly needs local runtime diagnosis.
|
|
295
393
|
- In `dev` mode, push is the finish line after `DEV-CLOSED` is recorded.
|
|
296
|
-
- In `verify` mode, Jenkins success, target environment verification, and closure record are mandatory.
|
|
394
|
+
- In `verify` mode, configured CI/Jenkins success, target environment verification, and closure record are mandatory only when the corresponding `verification.*_required` switch is enabled.
|
|
297
395
|
|
|
298
396
|
## Structure Policy
|
|
299
397
|
- Before coding, identify the right layer and reuse points.
|
|
@@ -309,10 +407,10 @@ Historical large-file debt can be listed in `structure.accepted_debt_paths` afte
|
|
|
309
407
|
- Purpose: single source of project config + workflow rules.
|
|
310
408
|
- How to record:
|
|
311
409
|
- Fill YAML frontmatter once.
|
|
312
|
-
- Keep target env front/backend usernames, Jenkins UI/API usernames, password fields or `*_password_env` references, commands, and docs paths here only.
|
|
410
|
+
- 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.
|
|
313
411
|
- Target environment also includes backend server root username/password.
|
|
314
412
|
- This file is expected to be committed to Git; prefer `*_password_env` for secrets so actual secret values stay in the current shell.
|
|
315
|
-
- Remaining environment keys are
|
|
413
|
+
- Remaining enabled environment keys are mandatory; blank values, TODO-like placeholders, and incorrect URL/path formats are treated as blocking errors by `doctor`.
|
|
316
414
|
- 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.
|
|
317
415
|
- Do not duplicate config elsewhere.
|
|
318
416
|
|
|
@@ -321,13 +419,15 @@ Historical large-file debt can be listed in `structure.accepted_debt_paths` afte
|
|
|
321
419
|
- How to record:
|
|
322
420
|
- Every task writes scope, risk, impact area, minimal design note, acceptance, evidence links.
|
|
323
421
|
- For code changes, record structure placement, reuse check, and whether ADR is needed.
|
|
422
|
+
- Keep this file active-only. Closed history belongs under `docs/tasks/archives/**`; an index-only file is not enough.
|
|
324
423
|
|
|
325
424
|
### 3) docs/tasks/closure-log.md
|
|
326
425
|
- Purpose: default lightweight closure record.
|
|
327
426
|
- How to record:
|
|
328
427
|
- Append one record per task.
|
|
329
|
-
- Required fields: task, commit, Jenkins
|
|
330
|
-
- If Jenkins failed then was fixed, also record failure reason and fix commit.
|
|
428
|
+
- Required fields: task, commit, configured CI/Jenkins status, target env status, structure check, result, follow-up.
|
|
429
|
+
- If CI/Jenkins failed then was fixed, also record failure reason and fix commit.
|
|
430
|
+
- Keep this file active-only. Historical closure records belong under `docs/tasks/archives/**`.
|
|
331
431
|
|
|
332
432
|
### 4) docs/architecture/
|
|
333
433
|
- Files:
|
|
@@ -346,10 +446,18 @@ Historical large-file debt can be listed in `structure.accepted_debt_paths` afte
|
|
|
346
446
|
- Accepted debt is not a fresh blocker unless it worsened or needs priority upgrade.
|
|
347
447
|
|
|
348
448
|
### 6) docs/design/
|
|
349
|
-
- Purpose: DD for cross-module / API / DB / deployment / Jenkins / key-page-flow changes.
|
|
449
|
+
- Purpose: DD for cross-module / API / DB / deployment / CI/Jenkins / key-page-flow changes.
|
|
350
450
|
- How to record:
|
|
351
451
|
- Small changes do not need a standalone DD file.
|
|
352
452
|
- Higher-risk changes create `docs/design/<TASK_ID>-<slug>.md`.
|
|
453
|
+
- Keep top-level `docs/design/T*.md` active-only. Historical DDs belong under `docs/archive/design/**`.
|
|
454
|
+
|
|
455
|
+
### 6.5) docs/tasks/archives/ and docs/archive/design/
|
|
456
|
+
- Purpose: physical history archives for closed taskbook entries, closure records, and old DDs.
|
|
457
|
+
- Rule:
|
|
458
|
+
- Archive by period or legacy bucket when active ledgers exceed `docs.active_*` budgets.
|
|
459
|
+
- `docs/tasks/archive-index.md` may summarize and link archives, but it is not the archive itself.
|
|
460
|
+
- `doctor` blocks over-budget active ledgers when `docs.ledger_block_on_exceed: true`.
|
|
353
461
|
|
|
354
462
|
### 7) docs/interfaces/
|
|
355
463
|
- Files:
|
|
@@ -380,7 +488,7 @@ These categories require stronger verification and usually a DD:
|
|
|
380
488
|
- Database migration
|
|
381
489
|
- Authentication / authorization
|
|
382
490
|
- Payment / order
|
|
383
|
-
- Deployment / Jenkins
|
|
491
|
+
- Deployment / CI / Jenkins
|
|
384
492
|
- Nginx / gateway
|
|
385
493
|
- File upload / download
|
|
386
494
|
- Production configuration
|
|
@@ -403,7 +511,7 @@ Development mode can also be forced per run:
|
|
|
403
511
|
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode dev --msg "<TASK_ID>: <summary>"
|
|
404
512
|
```
|
|
405
513
|
|
|
406
|
-
Verification mode runs the
|
|
514
|
+
Verification mode runs the configured CI/Jenkins + target-environment loop. Disabled surfaces are recorded as skipped:
|
|
407
515
|
|
|
408
516
|
```bash
|
|
409
517
|
python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> \
|
|
@@ -419,13 +527,15 @@ Manual verification commands remain available:
|
|
|
419
527
|
python3 docs/tools/autopipeline/ap.py verify-jenkins-build --git-ref HEAD
|
|
420
528
|
python3 docs/tools/autopipeline/ap.py wait-health --scope target
|
|
421
529
|
python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
|
|
422
|
-
python3 docs/tools/autopipeline/ap.py record-closure <TASK_ID> --commit HEAD --
|
|
530
|
+
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"
|
|
423
531
|
```
|
|
424
532
|
|
|
425
533
|
Available on-demand commands:
|
|
426
534
|
|
|
427
535
|
```bash
|
|
428
536
|
python3 docs/tools/autopipeline/ap.py doctor
|
|
537
|
+
python3 docs/tools/autopipeline/ap.py docs-ledger-check
|
|
538
|
+
python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
|
|
429
539
|
python3 docs/tools/autopipeline/ap.py verify-api-docs
|
|
430
540
|
python3 docs/tools/autopipeline/ap.py verify-jenkins
|
|
431
541
|
python3 docs/tools/autopipeline/ap.py verify-target --backend-path /health --frontend-path /
|
|
@@ -439,7 +549,7 @@ python3 docs/tools/autopipeline/ap.py check-matrix
|
|
|
439
549
|
python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
|
|
440
550
|
```
|
|
441
551
|
|
|
442
|
-
## Jenkins Build Tracking
|
|
552
|
+
## Optional Jenkins Build Tracking
|
|
443
553
|
|
|
444
554
|
- `verify-jenkins-build --git-ref HEAD`
|
|
445
555
|
- Use when Jenkins build descriptions include commit SHA and you want to find the latest build automatically.
|
|
@@ -10,21 +10,23 @@ developer_instructions = """
|
|
|
10
10
|
工作要求:
|
|
11
11
|
1. 优先用 rg / git / 项目脚本快速定位真实入口,再向下追踪调用链。
|
|
12
12
|
2. 先读项目已有文档、配置、路由、任务记录;涉及结构/优化时还要读结构标准、健康基线和优化 backlog。
|
|
13
|
-
3.
|
|
14
|
-
4.
|
|
15
|
-
5.
|
|
13
|
+
3. 必要时运行或建议 `ap.py classify --scope auto` 和 `ap.py docs-ledger-check`,说明风险级别、建议 gate scope、是否需要 DD/ADR/browser/CI-Jenkins/target verify,以及活跃 docs ledger 是否超预算;如超预算,只建议 `docs-ledger-archive --plan`,不要直接归档。
|
|
14
|
+
4. 输出根因时说明当前代码应归属的层级、现有同类模块、可复用 helper / 组件 / 脚本,以及是否触及 `structure.layer_rules`。
|
|
15
|
+
5. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
|
|
16
|
+
6. 输出内容必须尽量具体到:
|
|
16
17
|
- 文件路径
|
|
17
18
|
- 函数名 / 方法名
|
|
18
19
|
- 关键结构体 / 类 / 接口
|
|
19
20
|
- 关键配置项
|
|
20
|
-
|
|
21
|
-
|
|
21
|
+
7. 不要泛泛而谈,不要直接给大段修复方案。
|
|
22
|
+
8. 输出格式:
|
|
22
23
|
- 问题入口
|
|
23
24
|
- 调用链
|
|
24
25
|
- 关键文件
|
|
26
|
+
- 分类 / 风险 / 建议 gate
|
|
25
27
|
- 当前层级 / 归属模块
|
|
26
28
|
- 既有复用点
|
|
27
29
|
- 根因候选
|
|
28
30
|
- 建议交给哪个代理继续处理
|
|
29
|
-
|
|
31
|
+
9. 优先快速精准搜索,避免全仓库无差别扫描。
|
|
30
32
|
"""
|
|
@@ -13,15 +13,16 @@ developer_instructions = """
|
|
|
13
13
|
3. 除非明确要求,否则不要重构、不做大面积改名、不改无关文件。
|
|
14
14
|
4. 先跟随项目现有模式、helper、组件、脚本和文档约束,不新造不必要抽象。
|
|
15
15
|
5. 改代码前先确认业务层、应用层、基础设施层、接口/UI层、shared/tooling 的正确落位;不要把新职责塞进已经偏大的文件。
|
|
16
|
-
6.
|
|
17
|
-
7.
|
|
18
|
-
8.
|
|
19
|
-
9.
|
|
20
|
-
10.
|
|
21
|
-
11.
|
|
16
|
+
6. 遵守 `structure.layer_rules` import 边界;必须越界时先让主代理补 DD/ADR。
|
|
17
|
+
7. 新增工具、并发/缓存/请求封装、格式转换、权限判断、校验逻辑前,先搜索既有 helper、库、组件和脚本。
|
|
18
|
+
8. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
|
|
19
|
+
9. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
|
|
20
|
+
10. 如果修改涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界,交给 reviewer / 安全能力做只读复核。
|
|
21
|
+
11. 修改后运行聚焦门禁:优先项目 light gate,其次 docs-ledger-check、structure-check、相关测试、typecheck、lint、git diff --check,并确保 evidence.jsonl 记录实际执行;docs ledger 超预算时先输出 `docs-ledger-archive --plan`,只有主代理或用户确认后才执行 `--write`。
|
|
22
|
+
12. 修改后输出:
|
|
22
23
|
- 修改文件
|
|
23
24
|
- 修改点
|
|
24
25
|
- 修改原因
|
|
25
26
|
- 验证方法
|
|
26
|
-
|
|
27
|
+
13. 如发现问题超出小修范围,要立即停止并上报,不要自行扩大战场。
|
|
27
28
|
"""
|
|
@@ -10,14 +10,16 @@ developer_instructions = """
|
|
|
10
10
|
工作要求:
|
|
11
11
|
1. 优先检查:正确性、安全性、边界条件、异常路径、并发风险、事务一致性、缓存一致性、兼容性。
|
|
12
12
|
2. 结构/优化 review 必须先读 project-health-baseline 和 optimization-backlog;不要把 accepted debt 重新报告为当前 blocker。
|
|
13
|
-
3.
|
|
14
|
-
4.
|
|
15
|
-
5.
|
|
16
|
-
6.
|
|
13
|
+
3. 检查 `docs/tasks/evidence.jsonl`、closure-log 和实际命令输出是否一致;不要把未执行项写成 PASS。
|
|
14
|
+
4. 检查活跃 docs ledger 是否超过预算;`archive-index.md` 只是导航,不能替代 `docs/tasks/archives/**` 和 `docs/archive/design/**` 物理归档;需要归档时要求先审阅 `docs-ledger-archive --plan` 输出。
|
|
15
|
+
5. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
|
|
16
|
+
6. 以 git diff、相关测试、接口契约、真实运行证据、结构标准为基础,不凭风格偏好输出问题。
|
|
17
|
+
7. 优先输出真实问题,不要输出样式洁癖式意见。
|
|
18
|
+
8. 每条问题尽量包含:
|
|
17
19
|
- 问题点
|
|
18
20
|
- 影响范围
|
|
19
21
|
- 复现条件
|
|
20
22
|
- 建议修法
|
|
21
|
-
|
|
22
|
-
|
|
23
|
+
9. 发现测试不足时,指出应补哪些测试或验证路径。
|
|
24
|
+
10. 结论要按严重程度排序:P0 / P1 / P2 / P3,并明确是否影响当前任务完成。
|
|
23
25
|
"""
|