@elvis1513/auto-coding-skill 2.1.3 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +154 -548
  2. package/cli/assets/agents/browser-debugger.toml +0 -1
  3. package/cli/assets/agents/docs-researcher.toml +0 -1
  4. package/cli/assets/agents/explorer.toml +1 -2
  5. package/cli/assets/agents/fixer.toml +2 -3
  6. package/cli/assets/agents/reviewer.toml +1 -2
  7. package/cli/assets/skill/SKILL.md +98 -207
  8. package/cli/assets/skill/data/templates/ENGINEERING.md +113 -468
  9. package/cli/assets/skill/data/templates/docs/tasks/closure-log.md +11 -22
  10. package/cli/assets/skill/data/templates/docs/tasks/taskbook.md +16 -39
  11. package/cli/assets/skill/data/templates/tools/ap.py +16 -0
  12. package/cli/assets/skill/scripts/ap.py +666 -129
  13. package/cli/assets/skill/scripts/scaffold_templates.py +136 -0
  14. package/cli/src/index.js +317 -42
  15. package/cli/tests/ap_profiles_test.py +428 -0
  16. package/cli/tests/index.test.js +373 -62
  17. package/package.json +3 -3
  18. package/cli/assets/skill/data/templates/docs/architecture/adr/_TEMPLATE-ADR.md +0 -38
  19. package/cli/assets/skill/data/templates/docs/architecture/structure-standard.md +0 -92
  20. package/cli/assets/skill/data/templates/docs/bugs/bug-list.md +0 -5
  21. package/cli/assets/skill/data/templates/docs/deployment/deploy-records/_TEMPLATE-DEPLOY-RECORD.md +0 -19
  22. package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md +0 -11
  23. package/cli/assets/skill/data/templates/docs/design/_TEMPLATE-DD.md +0 -49
  24. package/cli/assets/skill/data/templates/docs/interfaces/api-change-log.md +0 -11
  25. package/cli/assets/skill/data/templates/docs/interfaces/api.md +0 -36
  26. package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md +0 -36
  27. package/cli/assets/skill/data/templates/docs/reviews/optimization-backlog.md +0 -25
  28. package/cli/assets/skill/data/templates/docs/reviews/project-health-baseline.md +0 -66
  29. package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md +0 -35
  30. package/cli/assets/skill/data/templates/docs/testing/regression-matrix.md +0 -11
@@ -1,6 +1,5 @@
1
1
  name = "browser_debugger"
2
2
  description = "浏览器调试代理,用于复现 UI 问题、收集控制台和网络证据。"
3
- model = "gpt-5.5"
4
3
  model_reasoning_effort = "xhigh"
5
4
  sandbox_mode = "workspace-write"
6
5
 
@@ -1,6 +1,5 @@
1
1
  name = "docs_researcher"
2
2
  description = "文档/API核对代理,负责确认框架、库、参数和版本行为。"
3
- model = "gpt-5.4-mini"
4
3
  model_reasoning_effort = "medium"
5
4
  sandbox_mode = "read-only"
6
5
 
@@ -1,6 +1,5 @@
1
1
  name = "explorer"
2
2
  description = "只读代码探索代理,用于定位调用链、关键文件和根因候选。"
3
- model = "gpt-5.4-mini"
4
3
  model_reasoning_effort = "medium"
5
4
  sandbox_mode = "read-only"
6
5
 
@@ -9,7 +8,7 @@ developer_instructions = """
9
8
 
10
9
  工作要求:
11
10
  1. 优先用 rg / git / 项目脚本快速定位真实入口,再向下追踪调用链。
12
- 2. 先读项目已有文档、配置、路由、任务记录;涉及结构/优化时还要读结构标准、健康基线和优化 backlog。
11
+ 2. 先读项目已有文档、配置、路由、任务记录;涉及结构/优化时,仅在结构标准、健康基线或优化 backlog 已存在时读取,不因可选文档缺失而阻塞。
13
12
  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
13
  4. 输出根因时说明当前代码应归属的层级、现有同类模块、可复用 helper / 组件 / 脚本,以及是否触及 `structure.layer_rules`。
15
14
  5. 如果根因依赖外部库、框架或版本行为,标记需要 docs_researcher / Context7 继续核对,不要凭记忆猜。
@@ -1,6 +1,5 @@
1
1
  name = "fixer"
2
2
  description = "实现型修复代理,适合小范围、快速、定点修改。"
3
- model = "gpt-5.3-codex-spark"
4
3
  model_reasoning_effort = "medium"
5
4
  sandbox_mode = "workspace-write"
6
5
 
@@ -12,8 +11,8 @@ developer_instructions = """
12
11
  2. 坚持“最小可辩护修改”原则。
13
12
  3. 除非明确要求,否则不要重构、不做大面积改名、不改无关文件。
14
13
  4. 先跟随项目现有模式、helper、组件、脚本和文档约束,不新造不必要抽象。
15
- 5. 改代码前先确认业务层、应用层、基础设施层、接口/UI层、shared/tooling 的正确落位;不要把新职责塞进已经偏大的文件。
16
- 6. 遵守 `structure.layer_rules` import 边界;必须越界时先让主代理补 DD/ADR。
14
+ 5. 改代码前先确认项目现有架构中的正确落位;不要默认项目采用 DDD/Clean Architecture,也不要仅因文件偏大而机械拆分。
15
+ 6. `structure.layer_rules` 仅在项目显式启用且设为 blocking 时构成硬门禁;advisory 结果作为复核信号,结合真实依赖关系判断。
17
16
  7. 新增工具、并发/缓存/请求封装、格式转换、权限判断、校验逻辑前,先搜索既有 helper、库、组件和脚本。
18
17
  8. 如果修改依赖外部 API / 版本行为,先让 docs_researcher / 文档 MCP 兜底确认。
19
18
  9. 如果修改影响 UI,交给 browser_debugger 或主代理做真实浏览器验证。
@@ -1,6 +1,5 @@
1
1
  name = "reviewer"
2
2
  description = "代码审查代理,聚焦正确性、安全性、回归风险和测试缺失。"
3
- model = "gpt-5.5"
4
3
  model_reasoning_effort = "xhigh"
5
4
  sandbox_mode = "read-only"
6
5
 
@@ -9,7 +8,7 @@ developer_instructions = """
9
8
 
10
9
  工作要求:
11
10
  1. 优先检查:正确性、安全性、边界条件、异常路径、并发风险、事务一致性、缓存一致性、兼容性。
12
- 2. 结构/优化 review 必须先读 project-health-baseline 和 optimization-backlog;不要把 accepted debt 重新报告为当前 blocker。
11
+ 2. 结构/优化 review 在 project-health-baseline 或 optimization-backlog 已存在时先读取;可选文档缺失不构成 blocker,也不要把已记录的 accepted debt 重复报告为当前问题。
13
12
  3. 检查 `docs/tasks/evidence.jsonl`、closure-log 和实际命令输出是否一致;不要把未执行项写成 PASS。
14
13
  4. 检查活跃 docs ledger 是否超过预算;`archive-index.md` 只是导航,不能替代 `docs/tasks/archives/**` 和 `docs/archive/design/**` 物理归档;需要归档时要求先审阅 `docs-ledger-archive --plan` 输出。
15
14
  5. 涉及鉴权、权限、支付、文件上传下载、部署、依赖或数据边界时,优先使用可用的安全扫描 / security review 能力辅助复核。
@@ -1,246 +1,137 @@
1
1
  ---
2
2
  name: auto-coding-skill
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.
3
+ description: Generic .agents engineering workflow with adaptive micro, standard, and high-risk execution profiles; minimal project scaffold; dev and verified closure modes.
4
4
  ---
5
5
 
6
- # Auto Coding Skill (.agents)
6
+ # Auto Coding Skill
7
7
 
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.
8
+ Use this skill for a disciplined task → design → implementation → verification
9
+ → closure workflow. The project keeps one manual configuration source:
10
+ `docs/ENGINEERING.md`.
9
11
 
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.
12
+ At task start, inventory installed skills, MCP servers, connectors, browser
13
+ tools, and repository scripts. Prefer the most direct authoritative capability.
14
+ Use subagents only when work is independent and the runtime supports them.
11
15
 
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.
16
+ ## Install and upgrade
13
17
 
14
- Use multi-agent roles deliberately. When the client exposes subagent tools and the active runtime policy permits delegation, split independent research, exploration, implementation, browser verification, and review work. When delegation is unavailable or restricted, execute the same role sequence in the main agent instead of pretending parallelism is possible.
15
-
16
- ## Supported clients
17
-
18
- - Any agent client or local workflow that reads the shared `.agents` layout.
18
+ ```bash
19
+ autocoding init
20
+ autocoding sync --projects .
21
+ pip install pyyaml requests
22
+ ```
19
23
 
20
- ## Tooling policy
24
+ New projects receive a minimal scaffold: the project-local skill, managed role
25
+ templates, `docs/ENGINEERING.md`, taskbook, closure log, and a small compatibility
26
+ launcher. Optional design, API, review, testing, deployment, and bug documents
27
+ are created only with `ap.py scaffold <group> --write`.
21
28
 
22
- Use the most direct authoritative capability for each task:
29
+ For existing projects:
23
30
 
24
- 1) Local repo work: use shell, repo scripts, and `docs/tools/autopipeline/ap.py` for edits, tests, gates, git, and project-local verification.
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.
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.
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.
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.
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.
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.
31
- 8) OpenAI/API keys and other secrets: use secure platform/key setup capabilities when available; do not paste, invent, or persist secrets outside the configured secure flow.
32
- 9) Screen/recent-work context: use Chronicle or screenshot skills when the user references visible UI state or recent manual actions.
33
- 10) Fall back to manual shell/code workflows only when the above are unavailable, insufficient, or slower than direct execution.
31
+ ```bash
32
+ autocoding sync --projects .
33
+ python3 docs/tools/autopipeline/ap.py upgrade --dry-run
34
+ python3 docs/tools/autopipeline/ap.py upgrade --write
35
+ ```
34
36
 
35
- ## Collaboration policy
37
+ Upgrade preserves project documents, custom agents, and explicit local model
38
+ overrides. Managed agents without a `model` inherit the current client model.
36
39
 
37
- Use `.agents/agents` role templates as the default collaboration model:
40
+ ## Configuration and profiles
38
41
 
39
- 1) `explorer`: read-only repo discovery, call-chain tracing, config mapping, and root-cause candidates.
40
- 2) `docs_researcher`: current external documentation, API signatures, version behavior, and compatibility checks.
41
- 3) `browser_debugger`: browser reproduction, console/network evidence, screenshots, and UI behavior verification.
42
- 4) `fixer`: bounded implementation after the cause and acceptance path are clear.
43
- 5) `reviewer`: read-only correctness, security, regression-risk, and missing-test review.
42
+ Read `docs/ENGINEERING.md` before choosing a path. `workflow.profile: auto`
43
+ resolves to exactly one execution profile:
44
44
 
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.
45
+ - `micro`: docs/tests-only or isolated low-risk work; changed gate; dev closure.
46
+ - `standard`: ordinary feature or defect work; standard gate; dev closure.
47
+ - `high-risk`: DB, auth, payment, deployment/build configuration, declared full
48
+ rules, or explicit verify work; real full gate; verify closure.
46
49
 
47
- ## Entry
50
+ High-risk signals cannot be manually downgraded. A full gate must use
51
+ `commands.gate_full` or `commands.full_gate`; light/standard fallbacks do not
52
+ count. An explicit non-auto configured profile replaces auto's low/normal
53
+ baseline but cannot suppress high-risk signals. CI/Jenkins and target
54
+ verification remain controlled by `verification.*_required`.
48
55
 
49
- 1) Install skill files into target repo:
56
+ Run:
50
57
 
51
58
  ```bash
52
- autocoding init
59
+ python3 docs/tools/autopipeline/ap.py doctor
60
+ python3 docs/tools/autopipeline/ap.py classify --scope auto
61
+ python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
53
62
  ```
54
63
 
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.
64
+ ## Development closure
56
65
 
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.
66
+ 1. Locate the real entry point, call chain, existing owner module, tests, and
67
+ reusable helpers.
68
+ 2. Update the active task with the smallest useful design note.
69
+ 3. Create DD/ADR only for cross-module, API, DB, deployment/CI, security, key UI
70
+ flow, or lasting structural decisions.
71
+ 4. Implement only necessary changes.
72
+ 5. Run the resolved gate.
73
+ 6. Record `DEV-CLOSED`, commit, push, and stop.
58
74
 
59
- 2) Initialize docs/tooling:
75
+ ## Verified closure
60
76
 
61
- ```bash
62
- python3 .agents/skills/auto-coding-skill/scripts/ap.py --repo . install
63
- ```
77
+ High-risk or explicitly verified work uses the strongest path:
64
78
 
65
- `install` refuses to overwrite existing generated docs/tooling unless `--force` is passed. Existing projects should use upgrade mode before replacing tracked docs:
79
+ 1. Run the real full local gate.
80
+ 2. Commit and push.
81
+ 3. Verify enabled CI/Jenkins and target-environment surfaces.
82
+ 4. Record `PASS`, `FAIL`, or `PARTIAL` only from executed evidence.
66
83
 
67
- ```bash
68
- python3 docs/tools/autopipeline/ap.py upgrade --dry-run
69
- python3 docs/tools/autopipeline/ap.py upgrade --write
70
- ```
84
+ ## Structure policy
85
+
86
+ Follow repository-native architecture first. Generic file-size, function-size,
87
+ and regex import rules are advisory unless the project explicitly sets
88
+ `structure.enforcement: blocking`. Search for reusable utilities, components,
89
+ clients, validation, permissions, caching, retry, and automation before adding
90
+ new helpers. Do not split files only to reduce line count.
71
91
 
72
- 3) Install runtime deps:
92
+ For repository-wide structural reviews, generate and read the health baseline
93
+ and optimization backlog. Accepted debt is not a fresh blocker unless it worsens.
73
94
 
74
95
  ```bash
75
- pip install pyyaml requests
96
+ python3 docs/tools/autopipeline/ap.py baseline init --write --update-config
76
97
  ```
77
98
 
78
- ## Single manual config source
79
-
80
- Fill only:
81
-
82
- - `docs/ENGINEERING.md` frontmatter
83
-
84
- This contains all manual fields:
85
- - `workflow.mode`
86
- - `commands.*`
87
- - `gate.*`
88
- - `structure.*`
89
- - `optimization.*`
90
- - `verification.*`
91
- - `runtime.*` (only for optional local diagnostics)
92
- - `target_env.*` (only required when `verification.target_env_required: true`)
93
- - `jenkins.*` (only required when `verification.jenkins_required: true`)
94
- - `docs.*`
95
-
96
- Do not duplicate config in other md/yaml files.
97
- Do not hide `docs/ENGINEERING.md` in `.gitignore`.
98
-
99
- Minimum required config for the default flow:
100
- - `workflow.mode`
101
- - `project.name`
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`:
107
- - `target_env.name`
108
- - `target_env.frontend_base_url`
109
- - `target_env.frontend_username`
110
- - `target_env.frontend_password` or `target_env.frontend_password_env`
111
- - `target_env.backend_base_url`
112
- - `target_env.backend_username`
113
- - `target_env.backend_password` or `target_env.backend_password_env`
114
- - `target_env.backend_root_username`
115
- - `target_env.backend_root_password` or `target_env.backend_root_password_env`
116
- - `target_env.health_base_url`
117
- - `target_env.health_path`
118
-
119
- Required only when `verification.jenkins_required: true`:
120
- - `jenkins.base_url`
121
- - `jenkins.ui_username`
122
- - `jenkins.ui_password` or `jenkins.ui_password_env`
123
- - `jenkins.api_user`
124
- - `jenkins.api_password` or `jenkins.api_password_env`
125
- - `jenkins.trigger_branch`
126
- - `jenkins.image_repository`
127
- - `jenkins.image_tag_strategy`
128
- - `jenkins.deploy_env`
129
- - `jenkins.job_url`
130
-
131
- ## Branch policy
132
-
133
- - `dev` is the long-lived integration branch.
134
- - Use a temporary task branch only when parallel work would otherwise collide on `dev`.
135
- - Keep temporary branches task-scoped and merge/rebase back into `dev` after closure.
136
-
137
- ## Execution order
138
-
139
- Read `workflow.mode` from `docs/ENGINEERING.md` before choosing the path.
140
-
141
- `dev` mode:
142
-
143
- 1) read `docs/ENGINEERING.md`
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
153
-
154
- `verify` mode:
155
-
156
- 1) read / update the same authoritative docs
157
- 2) run the default local lightweight gate
158
- 3) commit + push
159
- 4) verify configured CI/Jenkins build / deployment result when enabled
160
- 5) verify the real target environment when enabled
161
- 6) append `docs/tasks/closure-log.md` with `Result: PASS / FAIL / PARTIAL`
162
- 7) use summary / deployment record / regression matrix only when the task actually requires them
163
-
164
- ## Commands
165
-
166
- Default commands:
99
+ ## Collaboration roles
167
100
 
168
- ```bash
169
- python3 docs/tools/autopipeline/ap.py doctor
170
- python3 docs/tools/autopipeline/ap.py classify --scope auto
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
174
- python3 docs/tools/autopipeline/ap.py structure-check --scope auto
175
- python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
176
- python3 docs/tools/autopipeline/ap.py light-gate --scope full
177
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
178
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode dev --msg "<TASK_ID>: <summary>"
179
- python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode verify --msg "<TASK_ID>: <summary>" --backend-path /health --frontend-path /
180
- ```
101
+ Role templates provide behavior and permission boundaries, while the active
102
+ client supplies the available model unless a project keeps an explicit override.
103
+ `classify` recommends only roles justified by the effective profile:
181
104
 
182
- On-demand commands:
105
+ - `explorer`: read-only repository discovery and root-cause tracing.
106
+ - `docs_researcher`: current official API/version research.
107
+ - `browser_debugger`: UI reproduction and browser evidence.
108
+ - `fixer`: bounded implementation after scope is clear.
109
+ - `reviewer`: correctness, security, regression, and evidence review.
183
110
 
184
- ```bash
185
- python3 docs/tools/autopipeline/ap.py runtime-up
186
- python3 docs/tools/autopipeline/ap.py wait-health --scope runtime
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
191
- python3 docs/tools/autopipeline/ap.py structure-check --scope full
192
- python3 docs/tools/autopipeline/ap.py gate-profile
193
- python3 docs/tools/autopipeline/ap.py check-matrix
194
- python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
195
- ```
111
+ The main agent owns framing, architecture decisions, integration, verification,
112
+ closure records, and Git state.
113
+
114
+ ## Tool routing
196
115
 
197
- ## Engineering structure policy
198
-
199
- - Before coding, locate the existing layer, module owner, helper APIs, scripts, and tests for the behavior being changed.
200
- - Put new code in the correct layer: domain rules stay out of controllers/pages, orchestration belongs in application/service/usecase code, external systems belong behind infrastructure adapters, and UI components should not own deep business workflows.
201
- - Reuse before building: search existing utilities, components, clients, validation, permissions, caching, retry, formatting, and automation scripts before adding another helper.
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.
203
- - Never split files just to reduce line count. Split only when the business or technical boundary is clear, cohesion improves, tests can cover the move, and the change does not break transaction, state-machine, workflow, or reading continuity. Otherwise record or keep accepted debt and avoid adding new responsibilities.
204
- - 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.
205
- - `structure.layer_rules` enforces configurable import boundaries between domain, application, infrastructure, interface, and shared layers.
206
- - 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.
207
- - 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.
208
- - “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.
209
- - `baseline init` creates the first project health baseline and optimization backlog; use `--update-config` to seed `accepted_debt_paths`.
210
- - `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.
211
- - 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.
212
- - `docs.archive_index` is only navigation; an index without physical archive files does not satisfy ledger health.
213
- - `docs/tasks/evidence.jsonl` is the machine-readable execution trail for gates, verification, and closure. Keep it aligned with closure Markdown.
214
- - `gate-profile` summarizes local gate duration and failure history so small-step development can keep the fast path honest.
215
-
216
- ## Quality policy
217
-
218
- - Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/config checks.
219
- - 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`.
220
- - `light-gate` automatically runs `structure-check` when `structure.enabled: true` or `commands.structure_check` is configured.
221
- - 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.
222
- - 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.
223
- - `workflow.mode: dev` closes development after light gate, closure record, commit, and push.
224
- - `workflow.mode: verify` closes only after the configured CI/Jenkins and target-environment verification surfaces are satisfied.
225
- - `doctor` should be used early to catch missing or invalid config before the first implementation loop.
226
- - `doctor` runs the built-in docs ledger health check by default so projects do not accumulate giant taskbooks, closure logs, or active DD directories.
227
- - `light-gate` now fails if no usable fast gate command is configured.
228
- - `doctor`, `light-gate`, and `commit-push` all fail when required environment fields are missing, placeholder-like, or syntactically invalid.
229
- - Do not require local Docker Compose or full local regression for every small change.
230
- - CI/Jenkins and target environment verification are mandatory in `verify` mode only when `verification.jenkins_required` / `verification.target_env_required` are enabled.
231
- - `verify-target` should be used for real target-environment API/page checks when the task touches user-visible or deploy-sensitive behavior.
232
- - `commit-push` records closure automatically according to `workflow.mode`.
233
- - `regression-matrix.md` can mark `PASS` only after real execution with evidence.
234
- - 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.
235
-
236
- ## Multi-project operations
237
-
238
- Use the npm CLI from outside or inside a repo:
116
+ - Local code, tests, gates, and Git: shell, repository scripts, and `ap.py`.
117
+ - Current library/API behavior: official documentation MCP or matching skill.
118
+ - UI: in-app browser for local pages, Chrome for existing logged-in state,
119
+ Playwright for deterministic automation, Computer Use for unsupported native UI.
120
+ - PR/issue/CI state: GitHub connector; local Git for local changes and pushes.
121
+ - Design, security, analytics, and document artifacts: use the matching installed
122
+ skill or connector before manual recreation.
123
+ - Secrets: use configured environment references or secure platform flows; do
124
+ not invent values.
125
+
126
+ ## Optional documents and operations
239
127
 
240
128
  ```bash
241
- autocoding status --projects /path/to/repo1,/path/to/repo2
242
- autocoding sync --projects /path/to/repo1,/path/to/repo2 --dry-run
243
- autocoding sync --projects /path/to/repo1,/path/to/repo2
129
+ python3 docs/tools/autopipeline/ap.py scaffold all --write
130
+ python3 docs/tools/autopipeline/ap.py docs-ledger-check
131
+ python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
132
+ python3 docs/tools/autopipeline/ap.py gate-profile
133
+ python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
244
134
  ```
245
135
 
246
- `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`.
136
+ `status` and `sync` manage only the minimal required scaffold. Existing optional
137
+ documents and legacy tool copies are preserved but do not count as drift.