@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
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: auto-coding-skill
|
|
3
|
-
description: Use for a
|
|
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 (
|
|
6
|
+
# Auto Coding Skill (.agents)
|
|
7
7
|
|
|
8
|
-
This skill is for
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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,
|
|
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
|
|
54
|
-
# or claude / all
|
|
52
|
+
autocoding init
|
|
55
53
|
```
|
|
56
54
|
|
|
57
|
-
|
|
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
|
-
|
|
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)
|
|
132
|
-
3) read
|
|
133
|
-
4)
|
|
134
|
-
5)
|
|
135
|
-
6)
|
|
136
|
-
7)
|
|
137
|
-
8)
|
|
138
|
-
9)
|
|
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/
|
|
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
|
|
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
|
|
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: "
|
|
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
|
|
152
|
-
- `verify`:验证模式,完整闭环。轻量门禁、commit + push
|
|
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
|
|
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/
|
|
237
|
-
4) `docs/
|
|
238
|
-
5) `docs/
|
|
239
|
-
6) `docs/
|
|
240
|
-
7) `docs/
|
|
241
|
-
8) `docs/
|
|
242
|
-
9) `docs/
|
|
243
|
-
10) `docs/
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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 构建验证 →
|
|
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
|
|
504
|
+
`dev` 模式先写开发闭环再 commit + push;`verify` 模式 commit + push 后继续验证已启用的 CI/Jenkins 和目标环境。
|
|
407
505
|
|
|
408
|
-
6. Jenkins 验证
|
|
409
|
-
仅 `verify`
|
|
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
|
-
|
|
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`
|
|
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
|
|
7
|
-
|
|
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.
|