@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.
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: auto-coding-skill
3
- description: Use for a Claude/Codex engineering workflow with dev and verify modes. Initialize docs, fill docs/ENGINEERING.md once, then execute task->minimal-design->light-gate->DEV-CLOSED->push in dev mode, or full Jenkins->target-env->PASS closure in verify mode.
3
+ description: Use for a generic .agents engineering workflow with dev and verify modes. Initialize docs, fill docs/ENGINEERING.md once, then execute task->minimal-design->light-gate->DEV-CLOSED->push in dev mode, or full configured verification closure in verify mode.
4
4
  ---
5
5
 
6
- # Auto Coding Skill (Claude + Codex)
6
+ # Auto Coding Skill (.agents)
7
7
 
8
- This skill is for Go backend + frontend monorepo projects that rely on Jenkins to build and deploy after push. It supports both Claude and Codex. The default `dev` mode is optimized for fast development: lightweight local gate, early closure record, commit, push, then move to the next task. Use `verify` mode when Jenkins and the real target environment must be completed before closure.
8
+ This skill is for general software projects that need a disciplined task -> design -> implementation -> verification -> closure workflow. The default target is the shared `.agents/skills` and `.agents/agents` layout, independent of the client that loads it. The default `dev` mode is optimized for fast development: lightweight local gate, early closure record, commit, push, then move to the next task. Use `verify` mode when configured CI/Jenkins and real target environment checks must be completed before closure.
9
9
 
10
- `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory, must be filled with real values, and are committed as part of the project baseline. Secret fields may be represented either as direct `*_password` values for legacy projects or as `*_password_env` names that point to environment variables in the current shell. Unused environment keys should be removed from the template instead of being left as placeholders.
10
+ `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory only when their verification surface is enabled. Secret fields may be represented either as direct `*_password` values for legacy projects or as `*_password_env` names that point to environment variables in the current shell. Unused environment keys should be removed from the template instead of being left as placeholders.
11
11
 
12
12
  At task start, inventory the current client capabilities before choosing a route: installed MCP servers, local skills, plugins/apps/connectors, browser/control tools, and repo scripts. Prefer those capabilities when they provide current, authoritative, or directly inspectable state.
13
13
 
@@ -15,8 +15,7 @@ Use multi-agent roles deliberately. When the client exposes subagent tools and t
15
15
 
16
16
  ## Supported clients
17
17
 
18
- - Claude Code
19
- - Codex CLI
18
+ - Any agent client or local workflow that reads the shared `.agents` layout.
20
19
 
21
20
  ## Tooling policy
22
21
 
@@ -25,7 +24,7 @@ Use the most direct authoritative capability for each task:
25
24
  1) Local repo work: use shell, repo scripts, and `docs/tools/autopipeline/ap.py` for edits, tests, gates, git, and project-local verification.
26
25
  2) Current library/framework/API/CLI/cloud behavior: use a documentation MCP such as Context7 or the matching installed skill before coding migrations, config changes, or API integrations.
27
26
  3) Browser and UI verification: use Browser/in-app browser for localhost and app-owned sessions; use Chrome when the user's existing logged-in Chrome state is required; use Playwright for deterministic browser automation or terminal-first smoke tests; use Computer Use only for native apps or UI surfaces without a purpose-built connector.
28
- 4) Product/design sources: use Figma, Build Web Apps, Product Design, or frontend skills when the task depends on design context, visual implementation, screenshots, or generated UI.
27
+ 4) Product/design sources: use Figma, Build Web Apps, Product Design, or frontend/product-design skills when the task depends on design context, visual implementation, screenshots, or generated UI.
29
28
  5) GitHub/PR/CI state: use GitHub connectors for PRs, issues, review comments, and Actions/CI metadata; use local git for local diff, staging, commits, and pushes.
30
29
  6) Security-sensitive changes: use reviewer/security skills or security scan capabilities for auth, permission, payment, file transfer, deployment, dependency, and data-boundary changes.
31
30
  7) Analytical or document artifacts: use Data Analytics, documents, PDFs, spreadsheets, presentations, or LaTeX skills/plugins for those artifact types, including render/validation steps.
@@ -35,7 +34,7 @@ Use the most direct authoritative capability for each task:
35
34
 
36
35
  ## Collaboration policy
37
36
 
38
- Use `.agents/agents` role templates as the default collaboration model for Codex installs:
37
+ Use `.agents/agents` role templates as the default collaboration model:
39
38
 
40
39
  1) `explorer`: read-only repo discovery, call-chain tracing, config mapping, and root-cause candidates.
41
40
  2) `docs_researcher`: current external documentation, API signatures, version behavior, and compatibility checks.
@@ -43,24 +42,31 @@ Use `.agents/agents` role templates as the default collaboration model for Codex
43
42
  4) `fixer`: bounded implementation after the cause and acceptance path are clear.
44
43
  5) `reviewer`: read-only correctness, security, regression-risk, and missing-test review.
45
44
 
46
- The main agent always owns task framing, design decisions, integration, Jenkins / target-env verification, closure records, git state, and final delivery. Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
45
+ The main agent always owns task framing, design decisions, integration, configured CI / target-env verification, closure records, git state, and final delivery. Do not delegate a blocking architectural decision without keeping one agent responsible for final integration and correctness.
47
46
 
48
47
  ## Entry
49
48
 
50
49
  1) Install skill files into target repo:
51
50
 
52
51
  ```bash
53
- autocoding init --ai codex
54
- # or claude / all
52
+ autocoding init
55
53
  ```
56
54
 
57
- For Codex targets, this also installs the default subagent templates into `.agents/agents/`.
55
+ This also installs the managed default subagent templates into `.agents/agents/`. Existing custom agent files in `.agents/agents/` are preserved even when `--force` is used; managed template files with the same names are refreshed.
56
+
57
+ For non-current-directory installs, `--dest` accepts a repo root, a `.agents` directory, `.agents/skills`, or the direct `.agents/skills/auto-coding-skill` directory.
58
58
 
59
59
  2) Initialize docs/tooling:
60
60
 
61
61
  ```bash
62
62
  python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install
63
- # or .claude path
63
+ ```
64
+
65
+ `install` refuses to overwrite existing generated docs/tooling unless `--force` is passed. Existing projects should use upgrade mode before replacing tracked docs:
66
+
67
+ ```bash
68
+ python3 docs/tools/autopipeline/ap.py upgrade --dry-run
69
+ python3 docs/tools/autopipeline/ap.py upgrade --write
64
70
  ```
65
71
 
66
72
  3) Install runtime deps:
@@ -81,9 +87,10 @@ This contains all manual fields:
81
87
  - `gate.*`
82
88
  - `structure.*`
83
89
  - `optimization.*`
90
+ - `verification.*`
84
91
  - `runtime.*` (only for optional local diagnostics)
85
- - `target_env.*`
86
- - `jenkins.*`
92
+ - `target_env.*` (only required when `verification.target_env_required: true`)
93
+ - `jenkins.*` (only required when `verification.jenkins_required: true`)
87
94
  - `docs.*`
88
95
 
89
96
  Do not duplicate config in other md/yaml files.
@@ -93,6 +100,10 @@ Minimum required config for the default flow:
93
100
  - `workflow.mode`
94
101
  - `project.name`
95
102
  - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`, or `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
103
+ - `verification.target_env_required`
104
+ - `verification.jenkins_required`
105
+
106
+ Required only when `verification.target_env_required: true`:
96
107
  - `target_env.name`
97
108
  - `target_env.frontend_base_url`
98
109
  - `target_env.frontend_username`
@@ -104,6 +115,8 @@ Minimum required config for the default flow:
104
115
  - `target_env.backend_root_password` or `target_env.backend_root_password_env`
105
116
  - `target_env.health_base_url`
106
117
  - `target_env.health_path`
118
+
119
+ Required only when `verification.jenkins_required: true`:
107
120
  - `jenkins.base_url`
108
121
  - `jenkins.ui_username`
109
122
  - `jenkins.ui_password` or `jenkins.ui_password_env`
@@ -128,22 +141,23 @@ Read `workflow.mode` from `docs/ENGINEERING.md` before choosing the path.
128
141
  `dev` mode:
129
142
 
130
143
  1) read `docs/ENGINEERING.md`
131
- 2) read `docs/architecture/structure-standard.md` when the change adds or relocates code
132
- 3) read / update `docs/tasks/taskbook.md`
133
- 4) write minimal design notes; create a DD or ADR only when the change is cross-module, API, DB, deployment, Jenkins, key-page-flow, or long-term structure related
134
- 5) implement only the necessary changes
135
- 6) run the default local lightweight gate
136
- 7) append `docs/tasks/closure-log.md` with `Result: DEV-CLOSED`
137
- 8) commit + push
138
- 9) stop and start the next development task
144
+ 2) run or reason through `classify --scope auto` for changed work
145
+ 3) read `docs/architecture/structure-standard.md` when the change adds or relocates code
146
+ 4) read / update `docs/tasks/taskbook.md`
147
+ 5) write minimal design notes; create a DD or ADR only when the change is cross-module, API, DB, deployment, CI/Jenkins, key-page-flow, or long-term structure related
148
+ 6) implement only the necessary changes
149
+ 7) run the default local lightweight gate
150
+ 8) append `docs/tasks/closure-log.md` with `Result: DEV-CLOSED`
151
+ 9) commit + push
152
+ 10) stop and start the next development task
139
153
 
140
154
  `verify` mode:
141
155
 
142
156
  1) read / update the same authoritative docs
143
157
  2) run the default local lightweight gate
144
158
  3) commit + push
145
- 4) verify Jenkins build / deployment result
146
- 5) verify the real target environment
159
+ 4) verify configured CI/Jenkins build / deployment result when enabled
160
+ 5) verify the real target environment when enabled
147
161
  6) append `docs/tasks/closure-log.md` with `Result: PASS / FAIL / PARTIAL`
148
162
  7) use summary / deployment record / regression matrix only when the task actually requires them
149
163
 
@@ -153,7 +167,10 @@ Default commands:
153
167
 
154
168
  ```bash
155
169
  python3 docs/tools/autopipeline/ap.py doctor
170
+ python3 docs/tools/autopipeline/ap.py classify --scope auto
156
171
  python3 docs/tools/autopipeline/ap.py impact --scope auto
172
+ python3 docs/tools/autopipeline/ap.py docs-ledger-check
173
+ python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
157
174
  python3 docs/tools/autopipeline/ap.py structure-check --scope auto
158
175
  python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
159
176
  python3 docs/tools/autopipeline/ap.py light-gate --scope full
@@ -168,7 +185,11 @@ On-demand commands:
168
185
  python3 docs/tools/autopipeline/ap.py runtime-up
169
186
  python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
170
187
  python3 docs/tools/autopipeline/ap.py runtime-down
188
+ python3 docs/tools/autopipeline/ap.py upgrade --dry-run
189
+ python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
190
+ python3 docs/tools/autopipeline/ap.py docs-ledger-archive --write
171
191
  python3 docs/tools/autopipeline/ap.py structure-check --scope full
192
+ python3 docs/tools/autopipeline/ap.py gate-profile
172
193
  python3 docs/tools/autopipeline/ap.py check-matrix
173
194
  python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
174
195
  ```
@@ -180,25 +201,45 @@ python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
180
201
  - Reuse before building: search existing utilities, components, clients, validation, permissions, caching, retry, formatting, and automation scripts before adding another helper.
181
202
  - Do not add new responsibilities to large files. If a file exceeds `structure.max_file_lines_warn`, prefer extracting a focused module or component; if it exceeds `structure.max_file_lines_block`, only small fixes are acceptable unless the path is explicitly allowed.
182
203
  - Historical large files can be listed in `structure.accepted_debt_paths` only after they are recorded in the health baseline or optimization backlog; this does not permit large new additions to those files.
204
+ - `structure.layer_rules` enforces configurable import boundaries between domain, application, infrastructure, interface, and shared layers.
183
205
  - Self-built algorithms, concurrency controls, caches, protocol clients, or framework-like helpers require a concrete reason such as performance, concurrency, offline/deploy constraints, licensing, security, or compatibility, plus tests or benchmark/runtime evidence.
184
206
  - For structural reviews, read `docs/reviews/project-health-baseline.md` and `docs/reviews/optimization-backlog.md` first. Do not re-report accepted debt as a fresh blocker; report only new, worsened, unrecorded P0/P1, or backlog items that now deserve priority upgrade.
185
207
  - “Optimization complete” means the scoped P0/P1/P2 work is closed, local gate passes, no new unclassified P0/P1 exists, and remaining P2/P3 work is tracked or accepted debt.
208
+ - `baseline init` creates the first project health baseline and optimization backlog; use `--update-config` to seed `accepted_debt_paths`.
209
+ - `docs-ledger-check` enforces active documentation ledger budgets. `docs/tasks/taskbook.md`, `docs/tasks/closure-log.md`, and top-level `docs/design/T*.md` are active working sets, not unbounded history stores.
210
+ - When active ledger budgets are exceeded, run `docs-ledger-archive --plan`, inspect the plan, then run `docs-ledger-archive --write` only when the closed entries and DD files are correct. Add `--period 2026-06` only when backfilling a specific archive month. The archiver handles clearly closed task sections, non-conflicting closure records, and matching top-level `T*.md` DDs.
211
+ - `docs.archive_index` is only navigation; an index without physical archive files does not satisfy ledger health.
212
+ - `docs/tasks/evidence.jsonl` is the machine-readable execution trail for gates, verification, and closure. Keep it aligned with closure Markdown.
213
+ - `gate-profile` summarizes local gate duration and failure history so small-step development can keep the fast path honest.
186
214
 
187
215
  ## Quality policy
188
216
 
189
- - Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/Jenkins checks.
217
+ - Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/config checks.
190
218
  - For small-step development, prefer the generic impact-aware gate: `light-gate --scope auto`. The skill provides the gate engine; each project owns its commands and optional `gate.rules` path mapping in `docs/ENGINEERING.md`.
191
219
  - `light-gate` automatically runs `structure-check` when `structure.enabled: true` or `commands.structure_check` is configured.
192
220
  - Keep `standard` as the backward-compatible default when no `gate.*` policy is configured. Use `changed` only when project commands/rules make the reduced scope explicit.
193
221
  - Automatically upgrade to `full` for CI/deploy/build-tool/lockfile/autopipeline config changes, project-declared full rules, unknown impact when configured, or release/verify tasks.
194
222
  - `workflow.mode: dev` closes development after light gate, closure record, commit, and push.
195
- - `workflow.mode: verify` closes only after Jenkins and target-environment verification.
223
+ - `workflow.mode: verify` closes only after the configured CI/Jenkins and target-environment verification surfaces are satisfied.
196
224
  - `doctor` should be used early to catch missing or invalid config before the first implementation loop.
225
+ - `doctor` runs the built-in docs ledger health check by default so projects do not accumulate giant taskbooks, closure logs, or active DD directories.
197
226
  - `light-gate` now fails if no usable fast gate command is configured.
198
227
  - `doctor`, `light-gate`, and `commit-push` all fail when required environment fields are missing, placeholder-like, or syntactically invalid.
199
228
  - Do not require local Docker Compose or full local regression for every small change.
200
- - Jenkins and target environment verification are mandatory in `verify` mode, not in default `dev` mode.
229
+ - CI/Jenkins and target environment verification are mandatory in `verify` mode only when `verification.jenkins_required` / `verification.target_env_required` are enabled.
201
230
  - `verify-target` should be used for real target-environment API/page checks when the task touches user-visible or deploy-sensitive behavior.
202
231
  - `commit-push` records closure automatically according to `workflow.mode`.
203
232
  - `regression-matrix.md` can mark `PASS` only after real execution with evidence.
204
- - High-risk changes must include target environment verification and usually a DD.
233
+ - High-risk changes must include a DD and the strongest configured verification path; target-environment verification is required when `verification.target_env_required: true` or the task explicitly depends on runtime behavior.
234
+
235
+ ## Multi-project operations
236
+
237
+ Use the npm CLI from outside or inside a repo:
238
+
239
+ ```bash
240
+ autocoding status --projects /path/to/repo1,/path/to/repo2
241
+ autocoding sync --projects /path/to/repo1,/path/to/repo2 --dry-run
242
+ autocoding sync --projects /path/to/repo1,/path/to/repo2
243
+ ```
244
+
245
+ `status` reports drift in project-local `.agents`, managed agent templates, autopipeline scripts, missing template docs, and missing config keys. `sync` updates generated skill/tooling assets and only creates missing docs; it preserves custom files in `.agents/agents` and does not overwrite project-specific `docs/ENGINEERING.md`, which should be merged through `ap.py upgrade --write`.
@@ -5,7 +5,7 @@ workflow:
5
5
  project:
6
6
  name: ""
7
7
  repo_root: "."
8
- stack: "go-fullstack-monorepo"
8
+ stack: "generic"
9
9
  backend_dir: ""
10
10
  frontend_dir: ""
11
11
  go_main: ""
@@ -30,6 +30,7 @@ gate:
30
30
  fallback_scope: "standard"
31
31
  full_on_unknown: true
32
32
  no_change_scope: "standard"
33
+ profile_log: ".local/auto-coding-skill/gate-profile.jsonl"
33
34
  full_on:
34
35
  paths:
35
36
  - "Jenkinsfile"
@@ -65,7 +66,6 @@ structure:
65
66
  block_new_responsibility_in_large_file: true
66
67
  allow_large_files:
67
68
  - ".agents/skills/**"
68
- - ".claude/skills/**"
69
69
  - "docs/tools/autopipeline/**"
70
70
  - "generated/**"
71
71
  - "**/generated/**"
@@ -81,6 +81,63 @@ structure:
81
81
  - "**/*.bundle.js"
82
82
  - "**/*.map"
83
83
  accepted_debt_paths: []
84
+ layer_rules:
85
+ enabled: true
86
+ block: true
87
+ rules:
88
+ - name: "domain"
89
+ paths:
90
+ - "**/domain/**"
91
+ - "**/domains/**"
92
+ - "**/model/**"
93
+ - "**/models/**"
94
+ forbidden_imports:
95
+ - "**/infrastructure/**"
96
+ - "**/infra/**"
97
+ - "**/adapter/**"
98
+ - "**/repository/**"
99
+ - "**/repositories/**"
100
+ - "**/client/**"
101
+ - "**/clients/**"
102
+ - "**/controller/**"
103
+ - "**/handler/**"
104
+ - "**/page/**"
105
+ - "**/pages/**"
106
+ - "**/component/**"
107
+ - "**/components/**"
108
+ - "**/view/**"
109
+ - "**/views/**"
110
+ - name: "application"
111
+ paths:
112
+ - "**/application/**"
113
+ - "**/service/**"
114
+ - "**/services/**"
115
+ - "**/usecase/**"
116
+ - "**/usecases/**"
117
+ forbidden_imports:
118
+ - "**/controller/**"
119
+ - "**/handler/**"
120
+ - "**/page/**"
121
+ - "**/pages/**"
122
+ - "**/component/**"
123
+ - "**/components/**"
124
+ - "**/view/**"
125
+ - "**/views/**"
126
+ - name: "shared"
127
+ paths:
128
+ - "**/shared/**"
129
+ - "**/common/**"
130
+ - "**/utils/**"
131
+ - "**/lib/**"
132
+ forbidden_imports:
133
+ - "**/domain/**"
134
+ - "**/application/**"
135
+ - "**/service/**"
136
+ - "**/services/**"
137
+ - "**/infrastructure/**"
138
+ - "**/controller/**"
139
+ - "**/page/**"
140
+ - "**/pages/**"
84
141
  reusable_tool_dirs:
85
142
  - "docs/tools/**"
86
143
  - "scripts/**"
@@ -102,6 +159,10 @@ runtime:
102
159
  env_file: ""
103
160
  startup_timeout_sec: 120
104
161
 
162
+ verification:
163
+ target_env_required: true
164
+ jenkins_required: true
165
+
105
166
  target_env:
106
167
  name: ""
107
168
  frontend_base_url: ""
@@ -131,7 +192,16 @@ jenkins:
131
192
  docs:
132
193
  taskbook: "docs/tasks/taskbook.md"
133
194
  closure_log: "docs/tasks/closure-log.md"
195
+ evidence_log: "docs/tasks/evidence.jsonl"
134
196
  design_dir: "docs/design"
197
+ task_archive_dir: "docs/tasks/archives"
198
+ design_archive_dir: "docs/archive/design"
199
+ archive_index: "docs/tasks/archive-index.md"
200
+ ledger_check_enabled: true
201
+ ledger_block_on_exceed: true
202
+ active_taskbook_max_lines: 1200
203
+ active_closure_log_max_lines: 800
204
+ active_design_max_files: 120
135
205
  review_dir: "docs/reviews"
136
206
  health_baseline: "docs/reviews/project-health-baseline.md"
137
207
  optimization_backlog: "docs/reviews/optimization-backlog.md"
@@ -148,8 +218,8 @@ docs:
148
218
 
149
219
  目标:默认采用高效率开发闭环,并通过 `workflow.mode` 控制流程长度。
150
220
 
151
- - `dev`:开发模式,最快闭环。轻量门禁通过后,提前写 `DEV-CLOSED` 闭环,commit + push 触发 Jenkins 后结束。
152
- - `verify`:验证模式,完整闭环。轻量门禁、commit + push、Jenkins 构建验证、目标环境验证全部完成后,写 `PASS` 闭环。
221
+ - `dev`:开发模式,最快闭环。轻量门禁通过后,提前写 `DEV-CLOSED` 闭环,commit + push 后结束。
222
+ - `verify`:验证模式,完整闭环。轻量门禁、commit + push、已启用的 CI/Jenkins 构建验证和目标环境验证全部完成后,写 `PASS` 闭环。
153
223
 
154
224
  默认原则:
155
225
  - 默认不要求本地 Docker Compose 启动。
@@ -158,13 +228,14 @@ docs:
158
228
  - 默认不要求每个小改动生成长 summary。
159
229
  - 默认不要求 regression matrix 全 PASS。
160
230
  - 默认不要求 deployment record。
161
- - Jenkins 构建结果和目标环境真实验证,比本地模拟更重要。
231
+ - 已启用的 CI/Jenkins 构建结果和目标环境真实验证,比本地模拟更重要。
162
232
 
163
233
  补充规则:
164
234
  - 每次任务闭环后,必须清理临时文件、临时目录、日志、截图、构建缓存等非必要产物;仅明确需要保留的本地诊断目录允许保留。
165
235
  - 所有手工填写信息,只维护在本文件 frontmatter 中,其他文档不得重复配置。
166
236
  - `docs/ENGINEERING.md` 必须提交到 Git 管理,不允许写入 `.gitignore`。
167
237
  - 目标环境和 Jenkins 密码默认通过 `*_password_env` 指向当前 shell 中的环境变量;确需兼容旧项目时才使用明文 `*_password` 字段。
238
+ - 非 Jenkins 或本地-only 项目可以把 `verification.jenkins_required` / `verification.target_env_required` 设为 `false`,让 `doctor` 只检查通用门禁、文档和结构配置。
168
239
  - 未参与默认流程的环境项不要保留占位;模板中未保留的字段视为已清理,不再额外配置。
169
240
 
170
241
  ---
@@ -177,10 +248,15 @@ docs:
177
248
  - `gate.*`:按项目声明路径规则和高风险升级规则;未配置时保持标准门禁行为
178
249
  - `commands.structure_check`:可覆盖内置结构检查;留空时使用通用 `ap.py structure-check`
179
250
  - `structure.*`:通用工程结构阈值、允许的大文件模式、复用搜索目录
251
+ - `structure.layer_rules`:通用分层 import 边界检查;项目可按技术栈细化路径
180
252
  - `optimization.*`:健康基线感知的优化闭环口径,避免重复把已接受债务判定为当前未完成
253
+ - `verification.target_env_required` / `verification.jenkins_required`:控制 `doctor` 是否强校验目标环境和 Jenkins 配置
254
+ - `docs.evidence_log`:结构化证据 JSONL,记录 doctor / gate / verify / closure 等实际执行结果
255
+ - `docs.task_archive_dir` / `docs.design_archive_dir` / `docs.archive_index`:文档账本物理归档目录和导航索引;索引不能替代归档
256
+ - `docs.active_taskbook_max_lines` / `docs.active_closure_log_max_lines` / `docs.active_design_max_files`:活跃账本预算,超过后必须归档瘦身
181
257
  - `docs.health_baseline` / `docs.optimization_backlog` / `docs.structure_standard` / `docs.adr_dir`:项目结构治理文档位置
182
- - `target_env.*`:目标环境前端 / 后端地址、用户名、密码引用,必须全部填写且真实可用
183
- - `jenkins.*`:Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境,必须全部填写且真实可用
258
+ - `target_env.*`:当 `verification.target_env_required: true` 时,目标环境前端 / 后端地址、用户名、密码引用必须全部填写且真实可用
259
+ - `jenkins.*`:当 `verification.jenkins_required: true` 时,Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境必须全部填写且真实可用
184
260
 
185
261
  字段说明:
186
262
  - `target_env.backend_username` + `target_env.backend_password_env` 或 `target_env.backend_password`:目标环境后台账号
@@ -193,6 +269,10 @@ docs:
193
269
  - `workflow.mode`
194
270
  - `project.name`
195
271
  - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`,或 `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
272
+ - `verification.target_env_required`
273
+ - `verification.jenkins_required`
274
+
275
+ 当 `verification.target_env_required: true` 时必填:
196
276
  - `target_env.name`
197
277
  - `target_env.frontend_base_url`
198
278
  - `target_env.frontend_username`
@@ -204,6 +284,8 @@ docs:
204
284
  - `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
205
285
  - `target_env.health_base_url`
206
286
  - `target_env.health_path`
287
+
288
+ 当 `verification.jenkins_required: true` 时必填:
207
289
  - `jenkins.base_url`
208
290
  - `jenkins.ui_username`
209
291
  - `jenkins.ui_password` 或 `jenkins.ui_password_env`
@@ -217,13 +299,17 @@ docs:
217
299
 
218
300
  按需填写:
219
301
  - `gate.default_scope`:默认 `standard`;需要小步快跑时设为 `auto` 或 `changed`
302
+ - `gate.profile_log`:本地门禁耗时画像,默认写入 `.local/auto-coding-skill/gate-profile.jsonl`
220
303
  - `gate.rules`:项目自定义路径规则。每条规则可包含 `name`、`paths`、`commands`、`scope`
221
304
  - `structure.enabled`:是否把结构检查纳入 `light-gate`
305
+ - `structure.layer_rules.enabled` / `block`:是否检查分层 import 边界,以及违规时阻塞还是仅提示
222
306
  - `structure.max_file_lines_warn` / `structure.max_file_lines_block`:文件长度预警 / 阻塞阈值
223
307
  - `structure.max_added_lines_to_large_file`:禁止在已偏大的文件里继续大块堆职责
224
308
  - `structure.allow_large_files`:生成物、供应商代码、构建产物等允许超长或跳过结构检查的路径
225
309
  - `structure.accepted_debt_paths`:已记录为接受债务的历史大文件;只豁免历史体量,不豁免继续大幅新增
226
310
  - `optimization.completion_policy`:默认 `baseline-aware`,表示“优化完成”按本轮范围和已记录基线判断,不等于仓库没有任何可优化点
311
+ - `docs.ledger_check_enabled`:默认启用文档账本健康检查
312
+ - `docs.ledger_block_on_exceed`:默认阻塞超过预算的活跃账本;仅迁移期才允许临时关闭
227
313
  - `runtime.*`:仅在本地运行诊断时使用
228
314
  - `commands.build` / `commands.test` / `commands.quick_test` / `commands.lint` / `commands.typecheck` / `commands.format`:按项目实际情况保留
229
315
 
@@ -233,24 +319,28 @@ docs:
233
319
 
234
320
  1) `docs/ENGINEERING.md`
235
321
  2) `docs/tasks/taskbook.md`
236
- 3) `docs/design/**`
237
- 4) `docs/interfaces/api.md`
238
- 5) `docs/interfaces/api-change-log.md`
239
- 6) `docs/testing/regression-matrix.md`
240
- 7) `docs/bugs/bug-list.md`
241
- 8) `docs/tasks/closure-log.md`
242
- 9) `docs/tasks/summaries/**`
243
- 10) `docs/deployment/**`
244
- 11) 代码实现
322
+ 3) `docs/tasks/archives/**`
323
+ 4) `docs/design/**`
324
+ 5) `docs/archive/design/**`
325
+ 6) `docs/interfaces/api.md`
326
+ 7) `docs/interfaces/api-change-log.md`
327
+ 8) `docs/testing/regression-matrix.md`
328
+ 9) `docs/bugs/bug-list.md`
329
+ 10) `docs/tasks/closure-log.md`
330
+ 11) `docs/tasks/summaries/**`
331
+ 12) `docs/deployment/**`
332
+ 13) 代码实现
245
333
 
246
334
  说明:
247
335
  - `closure-log.md` 是每个任务默认必须留下的轻量闭环记录。
336
+ - `taskbook.md`、`closure-log.md` 和顶层 `docs/design/T*.md` 是活跃账本,不是永久历史仓库。超过预算时必须把已关闭历史内容物理归档到 `docs/tasks/archives/**` 和 `docs/archive/design/**`。
337
+ - `docs/tasks/archive-index.md` 只用于导航归档位置;只有索引、没有物理归档,不算完成账本瘦身。
248
338
  - `summaries/**` 只用于跨模块、高风险、阶段性里程碑、需要完整复盘的任务。
249
339
  - `deployment/**` 只用于真实部署记录、手工发布或高风险发布场景。
250
340
 
251
341
  ---
252
342
 
253
- ## 1.5 工具使用策略(Claude / Codex 专属)
343
+ ## 1.5 工具使用策略(通用 .agents 默认)
254
344
 
255
345
  任务开始时先做能力盘点:当前可用的 MCP servers、已安装 skills、plugins / apps / connectors、浏览器控制能力、repo 脚本。能直接读取权威状态、当前文档或真实 UI 的能力,优先于手写推测。
256
346
 
@@ -293,7 +383,7 @@ docs:
293
383
 
294
384
  ---
295
385
 
296
- ## 1.6 多 Agent 协作策略(Claude / Codex 专属)
386
+ ## 1.6 多 Agent 协作策略(通用 .agents 默认)
297
387
 
298
388
  默认使用 `.agents/agents` 中的角色模型来拆解任务;只有在当前客户端明确提供并允许子代理/多代理工具时,才实际并行派发。若运行时策略不允许子代理,则由主 agent 按同一角色顺序串行完成,不假装并行。
299
389
 
@@ -317,7 +407,7 @@ docs:
317
407
  主 agent 始终负责:
318
408
  - 任务定义、范围裁决、方案取舍
319
409
  - 代码集成和冲突处理
320
- - 轻量门禁、Jenkins/目标环境闭环
410
+ - 轻量门禁、已启用的 CI/Jenkins/目标环境闭环
321
411
  - 文档闭环、Git 状态、最终交付
322
412
 
323
413
  任务边界不清、需要强一致裁决或涉及架构取舍时,由主 agent 保持控制,不机械拆分。
@@ -348,8 +438,16 @@ docs:
348
438
  - 新会话做整体分析时,必须先读 `docs/reviews/project-health-baseline.md` 和 `docs/reviews/optimization-backlog.md`,只报告新增、恶化、未记录 P0/P1,或已记录但需要升级优先级的问题。
349
439
 
350
440
  5) 本地执行
441
+ - 任务开始分类:`python3 docs/tools/autopipeline/ap.py classify --scope auto`
351
442
  - 小步快跑默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope auto`
352
443
  - 发布、跨模块重构、架构调整默认执行:`python3 docs/tools/autopipeline/ap.py structure-check --scope full`
444
+ - 首次落基线:`python3 docs/tools/autopipeline/ap.py baseline init --write --update-config`
445
+ - 项目升级预检:`python3 docs/tools/autopipeline/ap.py upgrade --dry-run`
446
+ - 文档账本健康检查:`python3 docs/tools/autopipeline/ap.py docs-ledger-check`
447
+ - 文档账本归档预览:`python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan`
448
+ - 文档账本归档执行:`python3 docs/tools/autopipeline/ap.py docs-ledger-archive --write`
449
+ - 门禁耗时画像:`python3 docs/tools/autopipeline/ap.py gate-profile`
450
+ - `doctor` 默认纳入文档账本健康检查;`light-gate` 会先跑 `doctor`,因此活跃账本超预算会阻塞后续任务,避免“只建索引、不归档瘦身”的状态长期存在。
353
451
  - `light-gate` 在 `structure.enabled: true` 时会自动纳入结构检查;如项目需要更强规则,可配置 `commands.structure_check` 覆盖内置实现。
354
452
 
355
453
  ---
@@ -364,21 +462,21 @@ docs:
364
462
 
365
463
  规则:
366
464
  - 只跑最轻量门禁。
367
- - push 触发 Jenkins 后不等待、不轮询、不验证目标环境。
465
+ - push 后不等待、不轮询、不验证目标环境。
368
466
  - `closure-log.md` 必须提前写入本次提交。
369
467
  - 闭环结果写 `DEV-CLOSED`,不要伪装成完整 `PASS`。
370
- - Jenkins Build 写 `triggered by push, not verified in dev mode`。
468
+ - CI/Jenkins Build 写 `triggered by push, not verified in dev mode` 或项目等价表述。
371
469
  - Target Env 写 `not verified in dev mode`。
372
470
 
373
471
  ### 2.2 验证模式:`workflow.mode: "verify"`
374
472
 
375
473
  用于发布前、验收、高风险变更或需要完整证据的任务。默认闭环:
376
474
 
377
- 需求确认 → 最小设计 / 必要 DD → 开发实现 → 本地轻量校验 → commit + push → Jenkins 构建验证 → 目标环境验证 → 写 `PASS` 闭环
475
+ 需求确认 → 最小设计 / 必要 DD → 开发实现 → 本地轻量校验 → commit + push → 已启用的 CI/Jenkins 构建验证 → 已启用的目标环境验证 → 写 `PASS` 闭环
378
476
 
379
477
  规则:
380
- - Jenkins 构建必须成功。
381
- - 目标环境健康检查必须通过。
478
+ - 若 `verification.jenkins_required: true`,CI/Jenkins 构建必须成功。
479
+ - 若 `verification.target_env_required: true`,目标环境健康检查必须通过。
382
480
  - 关键接口 / 页面路径按任务需要补充验证。
383
481
  - 只有真实验证完成后,闭环结果才允许写 `PASS`。
384
482
  - 回归矩阵只有真实执行并有证据时才允许标 `PASS`。
@@ -386,10 +484,10 @@ docs:
386
484
  ### 2.3 任务步骤
387
485
 
388
486
  1. 需求确认
389
- 明确任务范围、影响服务、是否涉及 API/数据库/部署/Jenkins/前端页面。
487
+ 明确任务范围、影响服务、是否涉及 API/数据库/部署/CI/Jenkins/前端页面。
390
488
 
391
489
  2. 最小设计记录
392
- 普通小改动只更新 `taskbook` 或设计文档中的最小必要段落;跨模块、接口、数据库、部署、Jenkins、关键页面流程变更才补 DD。
490
+ 普通小改动只更新 `taskbook` 或设计文档中的最小必要段落;跨模块、接口、数据库、部署、CI/Jenkins、关键页面流程变更才补 DD。
393
491
 
394
492
  3. 开发实现
395
493
  只修改本次任务必要文件,不做无关重构。
@@ -400,25 +498,25 @@ docs:
400
498
  - 若未配置,则执行 `quick_test` / `test` / `build` 中最先配置的一项
401
499
  - `git diff --check`
402
500
  - API 文档检查
403
- - Jenkins 配置检查
501
+ - 已启用的 CI/Jenkins 配置检查
404
502
 
405
503
  5. 提交推送
406
- `dev` 模式先写开发闭环再 commit + push;`verify` 模式 commit + push 后继续验证 Jenkins 和目标环境。
504
+ `dev` 模式先写开发闭环再 commit + push;`verify` 模式 commit + push 后继续验证已启用的 CI/Jenkins 和目标环境。
407
505
 
408
- 6. Jenkins 验证
409
- 仅 `verify` 模式默认执行。查看 Jenkins 构建、镜像、部署结果;失败则根据 Jenkins 日志修复,再次提交推送。
506
+ 6. CI/Jenkins 验证
507
+ 仅 `verify` 模式且 `verification.jenkins_required: true` 时默认执行。查看 CI/Jenkins 构建、镜像、部署结果;失败则根据日志修复,再次提交推送。
410
508
 
411
509
  7. 目标环境验证
412
- 仅 `verify` 模式默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
510
+ 仅 `verify` 模式且 `verification.target_env_required: true` 时默认执行。在真实目标环境做健康检查、关键接口、关键页面或业务路径验证。
413
511
 
414
512
  8. 回归与证据记录
415
- 只有真实执行过 Jenkins / 目标环境验证,或显式要求本地运行验证时,才允许把 `regression-matrix.md` 标为 `PASS`。
513
+ 只有真实执行过已启用的 CI/Jenkins / 目标环境验证,或显式要求本地运行验证时,才允许把 `regression-matrix.md` 标为 `PASS`。
416
514
 
417
515
  9. 闭环记录
418
516
  每个任务必须留下轻量闭环记录。`dev` 模式用 `DEV-CLOSED`,`verify` 模式用 `PASS` / `FAIL` / `PARTIAL`。
419
517
 
420
518
  10. 配置入库
421
- `docs/ENGINEERING.md` 中保留下来的环境信息、前端/后端账号、Jenkins 账号与密码必须 100% 填写、正确填写,并提交 Git 作为项目权威配置持续维护。
519
+ `docs/ENGINEERING.md` 中保留下来的已启用环境信息、前端/后端账号、Jenkins 账号与密码必须 100% 填写、正确填写,并提交 Git 作为项目权威配置持续维护。
422
520
 
423
521
  ---
424
522
 
@@ -428,14 +526,14 @@ docs:
428
526
  - 数据库迁移
429
527
  - 鉴权 / 权限
430
528
  - 支付 / 订单
431
- - 部署 / Jenkins
529
+ - 部署 / CI / Jenkins
432
530
  - Nginx / 网关
433
531
  - 文件上传 / 下载
434
532
  - 生产配置
435
533
 
436
534
  高风险变更至少额外要求:
437
535
  - 明确 DD
438
- - 使用 `workflow.mode: "verify"`,或在 `dev` 快速闭环后显式补目标环境真实验证
536
+ - 使用 `workflow.mode: "verify"`,或在 `dev` 快速闭环后显式补已启用的目标环境真实验证
439
537
  - 闭环记录写清楚验证路径和结果
440
538
  - 必要时补 summary / deployment record / regression matrix
441
539
 
@@ -443,7 +541,7 @@ docs:
443
541
 
444
542
  ## 4. 本地 Docker 与完整回归(按需,不默认)
445
543
 
446
- 以下能力保留,但仅用于显式要求、问题复现、Jenkins/目标环境问题前置诊断:
544
+ 以下能力保留,但仅用于显式要求、问题复现、CI/Jenkins/目标环境问题前置诊断:
447
545
  - `runtime-up`
448
546
  - `runtime-down`
449
547
  - 本地 health check
@@ -1,8 +1,12 @@
1
1
  Follow `docs/ENGINEERING.md` strictly. Source of truth: `docs/ENGINEERING.md`.
2
+ At task start, use `ap.py classify --scope auto` when changed-file impact is not obvious.
2
3
  Before code changes, read the configured structure standard and place new code in the correct layer; do not add new responsibilities to already-large files.
4
+ Obey `structure.layer_rules` import boundaries unless a DD/ADR explicitly records the exception.
3
5
  Before optimization reviews, read the project health baseline and optimization backlog, and report only new, worsened, unrecorded P0/P1, or upgraded-priority items.
4
6
  Route work through already available MCP servers, installed skills, plugins, and app connectors when they provide current docs, design context, browser evidence, GitHub/CI state, security review, or artifact rendering.
5
7
  Use the `.agents/agents` role model when available: explorer, docs_researcher, browser_debugger, fixer, reviewer. If the client cannot run subagents, execute the same roles sequentially in the main agent.
6
- Default to the lightweight local gate first; when `structure.enabled` is true, the gate includes `structure-check`.
7
- Use Jenkins build verification and real target-environment verification as the primary completion gate in verify mode.
8
+ Default to the lightweight local gate first; `doctor` includes `docs-ledger-check`, and when `structure.enabled` is true the gate includes `structure-check`.
9
+ Keep active docs ledgers small: `taskbook.md`, `closure-log.md`, and top-level `docs/design/T*.md` must be physically archived when over budget. Use `docs-ledger-archive --plan` before `--write`; `archive-index.md` is only navigation.
10
+ Keep `docs/tasks/evidence.jsonl` and closure Markdown aligned with actual executed checks.
11
+ Use configured CI/Jenkins build verification and real target-environment verification as the primary completion gate in verify mode when their `verification.*_required` switches are enabled.
8
12
  Local Docker Compose and full local regression are on-demand diagnostic tools, not the default gate for every small change.