@anhlp/alp-core 0.0.1-beta.7 → 0.0.1-beta.8
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/dist/library-edit.d.ts +51 -2
- package/dist/library-edit.js +160 -8
- package/dist/library.d.ts +14 -1
- package/dist/library.js +73 -5
- package/dist/models.d.ts +35 -0
- package/dist/models.js +17 -1
- package/dist/packs.d.ts +57 -0
- package/dist/packs.js +247 -0
- package/dist/permissions.d.ts +3 -2
- package/dist/permissions.js +6 -3
- package/dist/profiles.js +3 -3
- package/dist/providers.d.ts +2 -4
- package/dist/providers.js +20 -4
- package/dist/skill-validate.d.ts +85 -0
- package/dist/skill-validate.js +298 -0
- package/dist/upgrade.d.ts +10 -0
- package/dist/upgrade.js +112 -6
- package/dist/validation.js +2 -3
- package/package.json +18 -2
- package/src/library-edit.js +170 -8
- package/src/library.js +96 -6
- package/src/models.js +24 -0
- package/src/packs.js +246 -0
- package/src/permissions.d.ts +3 -2
- package/src/permissions.js +13 -3
- package/src/profiles.js +4 -4
- package/src/providers.js +20 -5
- package/src/resolver.js +1 -1
- package/src/skill-validate.js +287 -0
- package/src/upgrade.js +54 -6
- package/src/validation.js +3 -4
- package/templates/ALP.md +52 -52
- package/templates/agents/lead/AGENT.md +77 -74
- package/templates/agents/main/AGENT.md +153 -145
- package/templates/agents/oracle/AGENT.md +38 -37
- package/templates/agents/peer/AGENT.md +56 -52
- package/templates/agents/reviewer/AGENT.md +63 -65
- package/templates/agents/supervisor/AGENT.md +63 -63
- package/templates/packs/architecture/agents/architect/AGENT.md +41 -0
- package/templates/packs/architecture/agents/architect/agent.json +5 -0
- package/templates/packs/architecture/agents/docs-maintainer/AGENT.md +33 -0
- package/templates/packs/architecture/agents/docs-maintainer/agent.json +4 -0
- package/templates/packs/architecture/pack.json +7 -0
- package/templates/packs/architecture/teams/blueprint/HOUSE_RULES.md +12 -0
- package/templates/packs/architecture/teams/blueprint/team.json +19 -0
- package/templates/packs/backend/pack.json +6 -0
- package/templates/packs/backend/skills/backend-development/SKILL.md +102 -0
- package/templates/packs/backend/skills/backend-development/references/api-design.md +96 -0
- package/templates/packs/backend/skills/backend-development/references/authentication.md +78 -0
- package/templates/packs/backend/skills/backend-development/references/error-handling.md +86 -0
- package/templates/packs/backend/skills/backend-development/references/testing.md +81 -0
- package/templates/packs/backend/skills/databases/SKILL.md +103 -0
- package/templates/packs/backend/skills/databases/references/query-performance.md +87 -0
- package/templates/packs/backend/skills/databases/references/schema-and-migrations.md +87 -0
- package/templates/packs/design/pack.json +6 -0
- package/templates/packs/design/skills/ui-design/SKILL.md +86 -0
- package/templates/packs/design/skills/ui-design/references/design-tokens.md +67 -0
- package/templates/packs/design/skills/ui-design/references/interaction-states.md +73 -0
- package/templates/packs/design/skills/ui-design/references/layout-and-typography.md +71 -0
- package/templates/packs/design/skills/ui-design/references/ui-review.md +83 -0
- package/templates/packs/frontend/pack.json +6 -0
- package/templates/packs/frontend/skills/frontend-development/SKILL.md +105 -0
- package/templates/packs/frontend/skills/frontend-development/references/accessibility.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/components-and-state.md +79 -0
- package/templates/packs/frontend/skills/frontend-development/references/data-fetching.md +86 -0
- package/templates/packs/frontend/skills/frontend-development/references/frameworks.md +77 -0
- package/templates/packs/frontend/skills/frontend-development/references/performance.md +78 -0
- package/templates/packs/integration/pack.json +6 -0
- package/templates/packs/integration/skills/mcp-integration/SKILL.md +100 -0
- package/templates/packs/integration/skills/mcp-integration/references/server-implementation.md +95 -0
- package/templates/packs/integration/skills/mcp-integration/references/testing.md +78 -0
- package/templates/packs/integration/skills/mcp-integration/references/tool-design.md +97 -0
- package/templates/packs/operations/pack.json +6 -0
- package/templates/packs/operations/skills/devops/SKILL.md +85 -0
- package/templates/packs/operations/skills/devops/references/ci-cd.md +84 -0
- package/templates/packs/operations/skills/devops/references/containers.md +85 -0
- package/templates/packs/operations/skills/devops/references/deployment-and-rollback.md +85 -0
- package/templates/packs/operations/skills/devops/references/observability.md +86 -0
- package/templates/packs/quality/pack.json +6 -0
- package/templates/packs/quality/skills/web-testing/SKILL.md +102 -0
- package/templates/packs/quality/skills/web-testing/references/e2e.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/performance-testing.md +85 -0
- package/templates/packs/quality/skills/web-testing/references/security-testing.md +78 -0
- package/templates/packs/quality/skills/web-testing/references/unit-and-component.md +78 -0
- package/templates/role-skills.json +4 -4
- package/templates/skills/architecture-docs/SKILL.md +81 -0
- package/templates/skills/architecture-docs/references/adr.md +62 -0
- package/templates/skills/architecture-docs/references/diagrams.md +60 -0
- package/templates/skills/architecture-docs/references/evidence-rules.md +49 -0
- package/templates/skills/bug-loop/SKILL.md +41 -40
- package/templates/skills/bug-loop/references/test-proof.md +21 -19
- package/templates/skills/compact/SKILL.md +2 -2
- package/templates/skills/curate/SKILL.md +6 -5
- package/templates/skills/feature-architecture/SKILL.md +90 -0
- package/templates/skills/feature-architecture/references/architecture-contract.md +95 -0
- package/templates/skills/feature-architecture/references/feature-design.md +69 -0
- package/templates/skills/feature-architecture/scripts/check-boundaries.mjs +270 -0
- package/templates/skills/goal-griller/SKILL.md +27 -27
- package/templates/skills/prompt-leverage/SKILL.md +29 -27
- package/templates/skills/prompt-leverage/references/brief-template.md +9 -9
- package/templates/skills/release-readiness/SKILL.md +83 -0
- package/templates/skills/release-readiness/references/checklist.md +40 -0
- package/templates/skills/release-readiness/references/verdict-template.md +53 -0
- package/templates/skills/safe-refactor/SKILL.md +84 -0
- package/templates/skills/safe-refactor/references/characterization-tests.md +57 -0
- package/templates/skills/safe-refactor/references/compatibility-checklist.md +56 -0
- package/templates/skills/security-review/SKILL.md +87 -0
- package/templates/skills/security-review/references/checklist.md +74 -0
- package/templates/skills/security-review/references/severity.md +61 -0
- package/templates/skills/sequence-execution-plan/SKILL.md +41 -38
- package/templates/skills/sequence-execution-plan/references/plan-template.md +5 -5
- package/templates/skills/skill-authoring/SKILL.md +84 -0
- package/templates/skills/skill-authoring/references/evaluation.md +45 -0
- package/templates/skills/skill-authoring/references/skill-anatomy.md +74 -0
- package/templates/skills/skill-authoring/references/trigger-design.md +52 -0
- package/templates/skills/smart-commits/SKILL.md +37 -36
- package/templates/skills/test-strategy/SKILL.md +83 -0
- package/templates/skills/test-strategy/references/contract-tests.md +46 -0
- package/templates/skills/test-strategy/references/risk-matrix.md +53 -0
- package/templates/skills/xia/SKILL.md +40 -38
- package/templates/teams/cafe/HOUSE_RULES.md +1 -1
- package/templates/teams/cafe/team.json +1 -1
- package/templates/teams/pho/HOUSE_RULES.md +1 -1
- package/templates/teams/pho/team.json +1 -1
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Contract kiến trúc
|
|
2
|
+
|
|
3
|
+
Đọc khi project đã có `docs/architecture/contract.json`, hoặc muốn có các quy tắc phụ thuộc
|
|
4
|
+
mà một công cụ kiểm thay vì để reviewer phải nhớ.
|
|
5
|
+
|
|
6
|
+
## Ưu tiên công cụ của chính project
|
|
7
|
+
|
|
8
|
+
Nếu project đã thực thi ranh giới sẵn (một quy tắc boundaries hay import của ESLint,
|
|
9
|
+
dependency-cruiser, Nx module boundaries, import-linter cho Python, ArchUnit cho Java,
|
|
10
|
+
hay một script riêng như `scripts/check-boundaries.mjs` của chính nó), hãy dùng nó và
|
|
11
|
+
dừng ở đây. Contract dưới đây là phương án dự phòng cho các repository JavaScript/TypeScript
|
|
12
|
+
chưa có gì. Việc nhận nó là quyết định của project: hãy đề xuất, đừng tự thêm vào.
|
|
13
|
+
|
|
14
|
+
## Định dạng
|
|
15
|
+
|
|
16
|
+
```json
|
|
17
|
+
{
|
|
18
|
+
"description": "Layers of the orders service",
|
|
19
|
+
"modules": {
|
|
20
|
+
"api": ["src/api/**"],
|
|
21
|
+
"app": ["src/app/**"],
|
|
22
|
+
"domain": ["src/domain/**"],
|
|
23
|
+
"shared": ["src/shared/**"]
|
|
24
|
+
},
|
|
25
|
+
"allow": {
|
|
26
|
+
"api": ["app", "shared"],
|
|
27
|
+
"app": ["domain", "shared"],
|
|
28
|
+
"domain": ["shared"],
|
|
29
|
+
"shared": []
|
|
30
|
+
},
|
|
31
|
+
"denyPackages": { "domain": ["express", "pg", "node:fs"] },
|
|
32
|
+
"ignore": ["**/*.test.ts", "**/__fixtures__/**"],
|
|
33
|
+
"exceptions": [
|
|
34
|
+
{ "file": "src/domain/legacy-report.ts", "import": "src/api/**",
|
|
35
|
+
"reason": "Report export predates the layering; removed by #412", "approvedBy": "main, 2026-11-05",
|
|
36
|
+
"expires": "2027-03-31" }
|
|
37
|
+
]
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- `modules`: tên -> các glob trên đường dẫn POSIX tương đối với repository (`**`, `*`, `?`).
|
|
42
|
+
Một file thuộc module đầu tiên có glob khớp; file không thuộc module nào thì không bị kiểm.
|
|
43
|
+
- `allow`: một module được liệt kê chỉ được import chính nó và các module được nêu tên. Module
|
|
44
|
+
không có trong `allow` thì không bị hạn chế, nên hãy liệt kê mọi module bạn muốn ràng buộc.
|
|
45
|
+
- `denyPackages`: tên package trần (hoặc builtin `node:`) mà một module không được import.
|
|
46
|
+
- `ignore`: các file không bao giờ bị kiểm.
|
|
47
|
+
- `exceptions`: bản ghi của việc chuyển lên. Mỗi mục cần `file` (một file, không dùng pattern),
|
|
48
|
+
`import` (một glob trên file bị import, hoặc một tên package; đừng bao giờ dùng `**`),
|
|
49
|
+
`reason` và `approvedBy`, và có thể có `expires` (YYYY-MM-DD; sau ngày đó nó không miễn gì
|
|
50
|
+
nữa). Chỉ thêm một mục sau khi quyết định đã được người sở hữu quy tắc đó đưa ra, đừng bao
|
|
51
|
+
giờ thêm để tự mình làm một phép kiểm đang fail lọt qua. Bộ kiểm sẽ liệt kê các exception
|
|
52
|
+
không ai cần.
|
|
53
|
+
|
|
54
|
+
## Thay đổi contract thì phải được review
|
|
55
|
+
|
|
56
|
+
Làm yếu contract (thêm một exception, nới `allow`, bỏ một package bị cấm, thêm một `ignore`,
|
|
57
|
+
đổi một module) sẽ làm mọi phép kiểm pass, nên đó là một quyết định giống như một exception.
|
|
58
|
+
Với `--base <git-ref>`, bộ kiểm so contract với bản ở ref đó và fail (thoát mã 1) với mọi chỗ
|
|
59
|
+
nới lỏng nó tìm thấy, nêu tên từng chỗ, cho tới khi lần chạy nói ra ai đã review
|
|
60
|
+
nó: `--approved-by "main, 2026-11-05"`. Siết chặt thì không cần review. Các gate chạy với
|
|
61
|
+
`--base` (`main` cho nhánh của một việc được giao, `origin/main` trong CI) và không bao giờ với
|
|
62
|
+
`--approved-by`; reviewer chạy cờ đó sau khi đã quyết.
|
|
63
|
+
|
|
64
|
+
## Bộ kiểm thấy những gì
|
|
65
|
+
|
|
66
|
+
`node <skill dir>/scripts/check-boundaries.mjs --root <repo> [--contract FILE] [--base REF [--approved-by NAME]] [--json]`
|
|
67
|
+
|
|
68
|
+
- Đọc `import ... from`, `export ... from`, `import '...'` dạng side-effect, `import('...')`
|
|
69
|
+
động và `require('...')`, bỏ qua comment, trong các file `.js .jsx .mjs .cjs .ts
|
|
70
|
+
.tsx .mts .cts` (bỏ qua `.d.ts`, `node_modules`, `dist`, `build`, `coverage`).
|
|
71
|
+
- Phân giải các specifier tương đối theo cách Node và TypeScript làm (phần mở rộng, `index.*`,
|
|
72
|
+
`./x.js` cho `./x.ts`). Alias đường dẫn (`@/x`, `paths` trong tsconfig) và specifier được
|
|
73
|
+
tính ra lúc chạy thì không được phân giải: project dùng alias cần công cụ riêng của nó.
|
|
74
|
+
- Thoát mã 0 là sạch, 1 là có vi phạm (`file:line from -> to (specifier): rule`) hoặc có một
|
|
75
|
+
chỗ nới lỏng chưa được review, 2 là contract, tham số hay base không hợp lệ. Nó chỉ đọc file
|
|
76
|
+
(và `git show <base>:<contract>`).
|
|
77
|
+
|
|
78
|
+
## Thực thi nó
|
|
79
|
+
|
|
80
|
+
Chỉ những quy tắc bộ kiểm xác minh được một cách đáng tin mới thuộc về một gate cứng.
|
|
81
|
+
|
|
82
|
+
- CI: thêm câu lệnh vào CI hoặc script test của project, với script được sao vào chính
|
|
83
|
+
repository (ví dụ `tools/check-boundaries.mjs`) để CI không cần thư viện ALP.
|
|
84
|
+
- ALP: một hook dạng blocking sẽ chặn một handoff, một lần đóng task hay một lần merge khi phép
|
|
85
|
+
kiểm còn fail; phần cuối output của nó là lý do agent đọc được. Một hook áp dụng cho các
|
|
86
|
+
agent nêu tên nó, nên người dùng (không phải agent) định nghĩa hook và cấp cho họ:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
alp hook add architecture --project --event handoff --command "node tools/check-boundaries.mjs --base main" --blocking --timeout 120
|
|
90
|
+
alp agent edit peer --project --hooks architecture
|
|
91
|
+
alp hook test architecture --project
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Dùng `--event task.close` (trên main hoặc lead) hay `--event merge` cho các gate còn lại.
|
|
95
|
+
Hook của project chỉ chạy khi người dùng đã tin workspace (`alp trust`).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Thiết kế feature
|
|
2
|
+
|
|
3
|
+
Đọc khi viết bản thiết kế feature, khi chọn feature tương tự, hoặc khi kiểm hướng của phụ thuộc mới.
|
|
4
|
+
|
|
5
|
+
## Chọn feature tương tự
|
|
6
|
+
|
|
7
|
+
Xếp hạng các ứng viên theo số điểm sau mà chúng chia sẻ với feature mới:
|
|
8
|
+
|
|
9
|
+
1. Cùng loại entry point (route HTTP, câu lệnh CLI, job, màn hình UI, event handler).
|
|
10
|
+
2. Cùng module hay lớp sở hữu, và cùng tập module mà nó phụ thuộc vào.
|
|
11
|
+
3. Cùng hình dạng lưu trữ hay tích hợp (đọc/ghi cùng một store hay service).
|
|
12
|
+
4. Mới được viết hoặc mới bị chạm tới, nên nó phản ánh quy ước hiện hành.
|
|
13
|
+
5. Có test theo phong cách project mong đợi.
|
|
14
|
+
|
|
15
|
+
Ưu tiên boilerplate hay generator của project khi có; dùng feature tương tự để bù phần
|
|
16
|
+
template bỏ sót. Nếu hai ứng viên mâu thuẫn nhau, hãy theo cái mà tài liệu kiến trúc hoặc
|
|
17
|
+
các phép kiểm hậu thuẫn, và ghi lại cái kia như một chỗ lệch.
|
|
18
|
+
|
|
19
|
+
Ghi lại lựa chọn đó trong bản thiết kế: "Mirrors `<path>` because <shared traits>."
|
|
20
|
+
|
|
21
|
+
## Mẫu thiết kế
|
|
22
|
+
|
|
23
|
+
Giữ nó vừa đủ cho những gì một reviewer cần để kiểm implementation. Bỏ các mục trống.
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
Feature: <one-line purpose>
|
|
27
|
+
Owning module: <module/package/layer>
|
|
28
|
+
Mirrors: <path of analogous feature or template> because <traits>
|
|
29
|
+
|
|
30
|
+
Hard constraints applied:
|
|
31
|
+
- <rule> (source: <doc/ADR/lint config>)
|
|
32
|
+
|
|
33
|
+
Files:
|
|
34
|
+
- add <path> <role in the feature>
|
|
35
|
+
- change <path> <what changes and why>
|
|
36
|
+
|
|
37
|
+
Public surface:
|
|
38
|
+
- <exported symbol / route / CLI flag / config key / event> new | changed
|
|
39
|
+
- Compatibility: <none affected | what callers must change>
|
|
40
|
+
|
|
41
|
+
Dependencies (from -> to):
|
|
42
|
+
- <module A> -> <module B> <existing edge kind it matches>
|
|
43
|
+
|
|
44
|
+
Tests:
|
|
45
|
+
- <test file> <behavior covered>
|
|
46
|
+
|
|
47
|
+
Open decisions / exceptions:
|
|
48
|
+
- <question or rule exception, who must decide>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Danh sách kiểm hướng phụ thuộc
|
|
52
|
+
|
|
53
|
+
Trả lời từng câu cho mỗi import, lời gọi hay lần đăng ký mới:
|
|
54
|
+
|
|
55
|
+
- Đã có một cạnh cùng loại chỉ theo hướng này chưa? Dẫn ra một cạnh.
|
|
56
|
+
- Cạnh đó có vượt một ranh giới lớp hay package mà tài liệu hoặc contract hạn chế không?
|
|
57
|
+
- Nó có tạo ra một vòng lặp giữa các module không? Kiểm cả hai hướng.
|
|
58
|
+
- Một module thấp hơn hoặc dùng chung bây giờ có import từ một module feature hay app không?
|
|
59
|
+
- Code domain hay core bây giờ có import một chi tiết framework, transport hay lưu trữ mà
|
|
60
|
+
feature tương tự vẫn giữ ở ngoài không?
|
|
61
|
+
- Một dependency chỉ dùng cho test hay chỉ dùng khi dev có thể chạm tới được từ code production
|
|
62
|
+
không?
|
|
63
|
+
- Feature có thò vào phần nội bộ của module khác thay vì vào entry point public của nó không?
|
|
64
|
+
- Một lần đăng ký mới (router, danh sách plugin, DI container, manifest) có được đặt đúng chỗ
|
|
65
|
+
mà feature tương tự đăng ký không?
|
|
66
|
+
|
|
67
|
+
Bất kỳ câu "có" nào về một lần vượt ranh giới bị hạn chế, một vòng lặp, hay một lần truy cập
|
|
68
|
+
phần nội bộ đều là vấn đề ràng buộc cứng: hãy sửa chỗ đặt, hoặc chuyển một quyết định ngoại lệ
|
|
69
|
+
lên trên trước khi hiện thực.
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// check-boundaries: checks a JavaScript/TypeScript repository's imports against its architecture
|
|
3
|
+
// contract (docs/architecture/contract.json by default). No dependencies, reads only, runs nothing.
|
|
4
|
+
//
|
|
5
|
+
// node check-boundaries.mjs [--root DIR] [--contract FILE] [--base GIT-REF [--approved-by NAME]] [--json]
|
|
6
|
+
//
|
|
7
|
+
// Its help, usage and error strings stay ENGLISH on purpose (t-d11c item 3, decided by the user
|
|
8
|
+
// 2026-11-06), even though the documentation around it is Vietnamese: this output is what the
|
|
9
|
+
// Blueprint house rules tell a peer to attach to a handoff, so a project's CI may match on it.
|
|
10
|
+
// Translating it would be a behaviour change for user projects, not a documentation fix.
|
|
11
|
+
//
|
|
12
|
+
// Exit 0: no violations. Exit 1: violations (each printed as file:line), or with --base a change to
|
|
13
|
+
// the contract that loosens it (an added exception, a wider allow list, a removed denied package, a
|
|
14
|
+
// new ignore, a changed module) not acknowledged with --approved-by. Exit 2: the contract or the
|
|
15
|
+
// arguments are invalid. The contract format is in ../references/architecture-contract.md.
|
|
16
|
+
import { execFile } from 'node:child_process';
|
|
17
|
+
import { readFile, readdir, stat } from 'node:fs/promises';
|
|
18
|
+
import { promisify } from 'node:util';
|
|
19
|
+
import path from 'node:path';
|
|
20
|
+
|
|
21
|
+
const SOURCE = /\.(?:[cm]?[jt]sx?)$/;
|
|
22
|
+
const EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
|
|
23
|
+
const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.alp']);
|
|
24
|
+
const KEYS = ['modules', 'allow', 'denyPackages', 'ignore', 'exceptions', '$schema', 'description'];
|
|
25
|
+
|
|
26
|
+
class ContractError extends Error {}
|
|
27
|
+
const toPosix = file => file.split(path.sep).join('/');
|
|
28
|
+
|
|
29
|
+
/** A glob (`**`, `*`, `?`) as a RegExp over POSIX paths relative to the root. */
|
|
30
|
+
export function globRegExp(glob) {
|
|
31
|
+
let out = '';
|
|
32
|
+
for (let i = 0; i < glob.length; i++) {
|
|
33
|
+
const c = glob[i];
|
|
34
|
+
if (c === '*' && glob[i + 1] === '*') { out += glob[i + 2] === '/' ? '(?:.*/)?' : '.*'; i += glob[i + 2] === '/' ? 2 : 1; }
|
|
35
|
+
else if (c === '*') out += '[^/]*';
|
|
36
|
+
else if (c === '?') out += '[^/]';
|
|
37
|
+
else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
|
|
38
|
+
}
|
|
39
|
+
return new RegExp(`^${out}$`);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Checks the contract's shape; returns it with compiled globs. */
|
|
43
|
+
export function parseContract(value, source = 'contract') {
|
|
44
|
+
const fail = message => { throw new ContractError(`${source}: ${message}`); };
|
|
45
|
+
const list = (v, where) => { if (!Array.isArray(v) || !v.every(x => typeof x === 'string' && x.trim())) fail(`${where} must be a list of strings`); return v; };
|
|
46
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) fail('expected a JSON object');
|
|
47
|
+
for (const key of Object.keys(value)) if (!KEYS.includes(key)) fail(`unknown key '${key}'; expected ${KEYS.join(', ')}`);
|
|
48
|
+
if (!value.modules || typeof value.modules !== 'object' || !Object.keys(value.modules).length) fail('modules must name at least one module and its globs');
|
|
49
|
+
const modules = Object.entries(value.modules).map(([name, globs]) => ({ name, globs: list(globs, `modules.${name}`).map(globRegExp) }));
|
|
50
|
+
const names = new Set(modules.map(m => m.name));
|
|
51
|
+
const allow = value.allow ?? {};
|
|
52
|
+
if (typeof allow !== 'object' || Array.isArray(allow)) fail('allow must map a module to the modules it may import');
|
|
53
|
+
for (const [from, targets] of Object.entries(allow)) {
|
|
54
|
+
if (!names.has(from)) fail(`allow names unknown module '${from}'`);
|
|
55
|
+
for (const target of list(targets, `allow.${from}`)) if (!names.has(target)) fail(`allow.${from} names unknown module '${target}'`);
|
|
56
|
+
}
|
|
57
|
+
const denyPackages = value.denyPackages ?? {};
|
|
58
|
+
for (const [from, packages] of Object.entries(denyPackages)) { if (!names.has(from)) fail(`denyPackages names unknown module '${from}'`); list(packages, `denyPackages.${from}`); }
|
|
59
|
+
const ignore = list(value.ignore ?? [], 'ignore').map(globRegExp);
|
|
60
|
+
const exceptions = (value.exceptions ?? []).map((exception, index) => {
|
|
61
|
+
const at = `exceptions[${index}]`;
|
|
62
|
+
if (!exception || typeof exception !== 'object') fail(`${at} must be an object`);
|
|
63
|
+
for (const key of ['file', 'import', 'reason', 'approvedBy']) if (typeof exception[key] !== 'string' || !exception[key].trim()) fail(`${at}.${key} is required: an exception records what it allows, why, and who approved it`);
|
|
64
|
+
for (const key of Object.keys(exception)) if (!['file', 'import', 'reason', 'approvedBy', 'expires'].includes(key)) fail(`${at}: unknown key '${key}'; expected file, import, reason, approvedBy, expires`);
|
|
65
|
+
// An exception is narrow: one file, and not every import.
|
|
66
|
+
if (/[*?]/.test(exception.file)) fail(`${at}.file must name one file, not a pattern: an exception covers a single file`);
|
|
67
|
+
if (/^\*\*?(\/\*\*?)*$/.test(exception.import.trim())) fail(`${at}.import must name what may be imported, not everything`);
|
|
68
|
+
if (exception.expires !== undefined && (typeof exception.expires !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(exception.expires) || Number.isNaN(Date.parse(exception.expires)))) fail(`${at}.expires must be a date, YYYY-MM-DD`);
|
|
69
|
+
return { ...exception, fileRe: globRegExp(exception.file), importRe: globRegExp(exception.import) };
|
|
70
|
+
});
|
|
71
|
+
return { modules, allow, denyPackages, ignore, exceptions };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* The source with comments as spaces and every string's contents as `x`, newlines kept, so
|
|
76
|
+
* positions match the original: imports are found in this mask (an import inside a string or a
|
|
77
|
+
* comment is not one) and their specifiers read back from the original at the same offsets.
|
|
78
|
+
*/
|
|
79
|
+
export function maskSource(text) {
|
|
80
|
+
let out = '';
|
|
81
|
+
let i = 0;
|
|
82
|
+
while (i < text.length) {
|
|
83
|
+
const c = text[i], n = text[i + 1];
|
|
84
|
+
if (c === '/' && n === '/') { while (i < text.length && text[i] !== '\n') { out += ' '; i++; } continue; }
|
|
85
|
+
if (c === '/' && n === '*') { out += ' '; i += 2; while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) { out += text[i] === '\n' ? '\n' : ' '; i++; } if (i < text.length) { out += ' '; i += 2; } continue; }
|
|
86
|
+
if (c === '"' || c === "'" || c === '`') {
|
|
87
|
+
out += c; i++;
|
|
88
|
+
while (i < text.length && text[i] !== c && !(c !== '`' && text[i] === '\n')) {
|
|
89
|
+
if (text[i] === '\\' && i + 1 < text.length) { out += 'xx'; i += 2; continue; }
|
|
90
|
+
out += text[i] === '\n' ? '\n' : 'x'; i++;
|
|
91
|
+
}
|
|
92
|
+
if (i < text.length) { out += text[i]; i++; }
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
out += c; i++;
|
|
96
|
+
}
|
|
97
|
+
return out;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** Every module specifier a source file imports, with its line: import/export from, import(), require(). */
|
|
101
|
+
export function importsOf(text) {
|
|
102
|
+
const masked = maskSource(text);
|
|
103
|
+
const found = [];
|
|
104
|
+
const patterns = [/(?<![.\w$])from\s*(['"])(x+)\1/g, /(?<![.\w$])import\s*(['"])(x+)\1/g, /(?<![.\w$])import\s*\(\s*(['"])(x+)\1\s*\)/g, /(?<![.\w$])require\s*\(\s*(['"])(x+)\1\s*\)/g];
|
|
105
|
+
for (const pattern of patterns) {
|
|
106
|
+
for (const match of masked.matchAll(pattern)) {
|
|
107
|
+
const at = match.index + match[0].lastIndexOf(match[2]);
|
|
108
|
+
found.push({ specifier: text.slice(at, at + match[2].length), line: masked.slice(0, at).split('\n').length });
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return found.sort((a, b) => a.line - b.line);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** The package a bare specifier names: `@scope/name`, `name`, or `node:x`. */
|
|
115
|
+
const packageOf = specifier => specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
|
|
116
|
+
|
|
117
|
+
async function exists(file) { return stat(file).then(info => info.isFile(), () => false); }
|
|
118
|
+
|
|
119
|
+
/** A relative specifier resolved to a repository file, as TypeScript and Node would find it. */
|
|
120
|
+
async function resolveRelative(root, fromFile, specifier) {
|
|
121
|
+
const base = path.resolve(root, path.dirname(fromFile), specifier);
|
|
122
|
+
const candidates = [base, ...EXTENSIONS.map(ext => base + ext), ...EXTENSIONS.map(ext => path.join(base, `index${ext}`))];
|
|
123
|
+
// TypeScript's ESM style imports ./x.js for ./x.ts.
|
|
124
|
+
if (/\.[cm]?js$/.test(base)) candidates.push(...['.ts', '.tsx', '.mts', '.cts'].map(ext => base.replace(/\.[cm]?js$/, ext)));
|
|
125
|
+
for (const candidate of candidates) if (await exists(candidate)) return toPosix(path.relative(root, candidate));
|
|
126
|
+
return toPosix(path.relative(root, base));
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
async function sourceFiles(root, ignore) {
|
|
130
|
+
const files = [];
|
|
131
|
+
const walk = async relative => {
|
|
132
|
+
for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
|
|
133
|
+
const rel = relative ? `${relative}/${entry.name}` : entry.name;
|
|
134
|
+
if (entry.isDirectory()) { if (!SKIP_DIRS.has(entry.name)) await walk(rel); }
|
|
135
|
+
else if (entry.isFile() && SOURCE.test(entry.name) && !entry.name.endsWith('.d.ts') && !ignore.some(re => re.test(rel))) files.push(rel);
|
|
136
|
+
}
|
|
137
|
+
};
|
|
138
|
+
await walk('');
|
|
139
|
+
return files.sort();
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Checks `root` against its contract.
|
|
144
|
+
* @returns {Promise<{ files: number, violations: Array<{ file: string, line: number, from: string, to: string, specifier: string, rule: string }>, excepted: Array<object> }>}
|
|
145
|
+
*/
|
|
146
|
+
export async function checkBoundaries(root, contractValue, { today = new Date() } = {}) {
|
|
147
|
+
const contract = parseContract(contractValue);
|
|
148
|
+
const day = today.toISOString().slice(0, 10);
|
|
149
|
+
const used = new Set();
|
|
150
|
+
const moduleOf = file => contract.modules.find(m => m.globs.some(re => re.test(file)))?.name;
|
|
151
|
+
const violations = [];
|
|
152
|
+
const excepted = [];
|
|
153
|
+
let checked = 0;
|
|
154
|
+
for (const file of await sourceFiles(root, contract.ignore)) {
|
|
155
|
+
const from = moduleOf(file);
|
|
156
|
+
if (!from) continue;
|
|
157
|
+
checked++;
|
|
158
|
+
const text = await readFile(path.join(root, file), 'utf8');
|
|
159
|
+
for (const { specifier, line } of importsOf(text)) {
|
|
160
|
+
let finding;
|
|
161
|
+
if (specifier.startsWith('.') || specifier.startsWith('/')) {
|
|
162
|
+
const target = await resolveRelative(root, file, specifier);
|
|
163
|
+
const to = moduleOf(target);
|
|
164
|
+
const allowed = contract.allow[from];
|
|
165
|
+
if (to && to !== from && allowed && !allowed.includes(to)) finding = { file, line, from, to, specifier, target, rule: `${from} may import only ${allowed.length ? allowed.join(', ') : 'itself'}` };
|
|
166
|
+
} else {
|
|
167
|
+
const pkg = packageOf(specifier);
|
|
168
|
+
const denied = contract.denyPackages[from] ?? [];
|
|
169
|
+
if (denied.includes(pkg) || denied.includes(specifier)) finding = { file, line, from, to: pkg, specifier, target: pkg, rule: `${from} must not import package ${pkg}` };
|
|
170
|
+
}
|
|
171
|
+
if (!finding) continue;
|
|
172
|
+
const exception = contract.exceptions.find(e => e.fileRe.test(file) && e.importRe.test(finding.target));
|
|
173
|
+
if (exception) used.add(exception);
|
|
174
|
+
// An exception that has expired excuses nothing: the decision is to be made again.
|
|
175
|
+
if (exception && exception.expires && exception.expires < day) violations.push({ ...finding, rule: `${finding.rule} (its exception expired on ${exception.expires}; approved by ${exception.approvedBy})` });
|
|
176
|
+
else if (exception) excepted.push({ ...finding, reason: exception.reason, approvedBy: exception.approvedBy, ...(exception.expires ? { expires: exception.expires } : {}) });
|
|
177
|
+
else violations.push(finding);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
// An exception nothing needs any more: listed for review, so stale permissions do not pile up.
|
|
181
|
+
const unused = contract.exceptions.filter(e => !used.has(e)).map(({ fileRe, importRe, ...e }) => e);
|
|
182
|
+
return { files: checked, violations, excepted, unusedExceptions: unused };
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
const key = exception => `${exception.file} -> ${exception.import}`;
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* The ways `current` loosens `base` (both contract objects): what a reviewer must approve. Tightening
|
|
189
|
+
* (a new denied package, a narrower allow list, a removed exception) is not listed.
|
|
190
|
+
* @returns {string[]}
|
|
191
|
+
*/
|
|
192
|
+
export function contractLoosening(base, current) {
|
|
193
|
+
const changes = [];
|
|
194
|
+
const modules = new Set([...Object.keys(base.modules ?? {}), ...Object.keys(current.modules ?? {})]);
|
|
195
|
+
for (const name of modules) {
|
|
196
|
+
const before = JSON.stringify([...(base.modules?.[name] ?? [])].sort());
|
|
197
|
+
const after = JSON.stringify([...(current.modules?.[name] ?? [])].sort());
|
|
198
|
+
if (base.modules?.[name] && before !== after) changes.push(`modules.${name} changed from ${before} to ${after}: files may have left the module`);
|
|
199
|
+
}
|
|
200
|
+
for (const [name, targets] of Object.entries(base.allow ?? {})) {
|
|
201
|
+
if (!Object.hasOwn(current.allow ?? {}, name)) { changes.push(`allow.${name} was removed: ${name} may now import any module`); continue; }
|
|
202
|
+
for (const target of current.allow[name]) if (!targets.includes(target)) changes.push(`allow.${name} adds ${target}`);
|
|
203
|
+
}
|
|
204
|
+
for (const [name, packages] of Object.entries(base.denyPackages ?? {})) {
|
|
205
|
+
for (const pkg of packages) if (!(current.denyPackages?.[name] ?? []).includes(pkg)) changes.push(`denyPackages.${name} no longer denies ${pkg}`);
|
|
206
|
+
}
|
|
207
|
+
for (const glob of current.ignore ?? []) if (!(base.ignore ?? []).includes(glob)) changes.push(`ignore adds ${glob}`);
|
|
208
|
+
const before = new Map((base.exceptions ?? []).map(e => [key(e), e]));
|
|
209
|
+
for (const exception of current.exceptions ?? []) {
|
|
210
|
+
const old = before.get(key(exception));
|
|
211
|
+
if (!old) changes.push(`exception added: ${key(exception)} (${exception.reason}; approved by ${exception.approvedBy}${exception.expires ? `; expires ${exception.expires}` : ''})`);
|
|
212
|
+
else if (old.reason !== exception.reason || old.approvedBy !== exception.approvedBy || (old.expires ?? '') !== (exception.expires ?? '')) changes.push(`exception changed: ${key(exception)} (now ${exception.reason}; approved by ${exception.approvedBy}${exception.expires ? `; expires ${exception.expires}` : '; no expiry'})`);
|
|
213
|
+
}
|
|
214
|
+
return changes;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** The contract as git has it at `ref`, or undefined when it did not exist there. */
|
|
218
|
+
async function contractAt(root, ref, relative) {
|
|
219
|
+
try {
|
|
220
|
+
const { stdout } = await promisify(execFile)('git', ['-C', root, 'show', `${ref}:${relative}`], { maxBuffer: 4 * 1024 * 1024 });
|
|
221
|
+
try { return JSON.parse(stdout); } catch (error) { throw new ContractError(`${relative} at ${ref}: ${error.message}`); }
|
|
222
|
+
} catch (error) {
|
|
223
|
+
if (error instanceof ContractError) throw error;
|
|
224
|
+
if (/exists on disk, but not in|does not exist in|path .* does not exist/.test(String(error.stderr ?? ''))) return undefined;
|
|
225
|
+
throw new ContractError(`cannot read ${relative} at ${ref}: ${String(error.stderr ?? error.message).trim()}`);
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
async function main(argv) {
|
|
230
|
+
const VALUED = ['--root', '--contract', '--base', '--approved-by'];
|
|
231
|
+
const arg = name => { const at = argv.indexOf(name); if (at < 0) return undefined; const value = argv[at + 1]; if (value === undefined || value.startsWith('--')) throw new ContractError(`${name} needs a value`); return value; };
|
|
232
|
+
const unknown = argv.filter((a, i) => (a.startsWith('--') && !['--json', ...VALUED].includes(a)) || (!a.startsWith('--') && !VALUED.includes(argv[i - 1])));
|
|
233
|
+
if (unknown.length) throw new ContractError(`unknown argument ${unknown[0]}; use --root DIR, --contract FILE, --base GIT-REF, --approved-by NAME, --json`);
|
|
234
|
+
if (argv.includes('--approved-by') && !argv.includes('--base')) throw new ContractError('--approved-by acknowledges contract changes found with --base');
|
|
235
|
+
const root = path.resolve(arg('--root') ?? process.cwd());
|
|
236
|
+
const contractFile = path.resolve(root, arg('--contract') ?? 'docs/architecture/contract.json');
|
|
237
|
+
let text;
|
|
238
|
+
try { text = await readFile(contractFile, 'utf8'); }
|
|
239
|
+
catch { throw new ContractError(`no contract at ${contractFile}; write one (see references/architecture-contract.md) or pass --contract`); }
|
|
240
|
+
let value;
|
|
241
|
+
try { value = JSON.parse(text); } catch (error) { throw new ContractError(`${contractFile}: ${error.message}`); }
|
|
242
|
+
const result = await checkBoundaries(root, value);
|
|
243
|
+
const relative = toPosix(path.relative(root, contractFile));
|
|
244
|
+
// A weaker contract makes the check pass too: with --base, loosening it needs an acknowledged review.
|
|
245
|
+
const base = arg('--base');
|
|
246
|
+
const approvedBy = arg('--approved-by');
|
|
247
|
+
let contractChanges = [];
|
|
248
|
+
if (base) {
|
|
249
|
+
const before = await contractAt(root, base, relative);
|
|
250
|
+
contractChanges = before === undefined ? [] : contractLoosening(before, value);
|
|
251
|
+
}
|
|
252
|
+
const unreviewed = contractChanges.length && !approvedBy;
|
|
253
|
+
if (argv.includes('--json')) console.log(JSON.stringify({ contract: relative, ...result, ...(base ? { base, contractChanges, ...(approvedBy ? { approvedBy } : {}) } : {}) }, null, 2));
|
|
254
|
+
else {
|
|
255
|
+
for (const v of result.violations) console.log(`${v.file}:${v.line} ${v.from} -> ${v.to} (${v.specifier}): ${v.rule}`);
|
|
256
|
+
for (const e of result.excepted) console.log(`${e.file}:${e.line} ${e.from} -> ${e.to}: allowed by exception (${e.reason}; approved by ${e.approvedBy}${e.expires ? `; expires ${e.expires}` : ''})`);
|
|
257
|
+
for (const e of result.unusedExceptions) console.log(`unused exception: ${key(e)} (${e.reason}; approved by ${e.approvedBy}): nothing needs it; remove it`);
|
|
258
|
+
for (const change of contractChanges) console.log(`contract change since ${base}${approvedBy ? `, approved by ${approvedBy}` : ', needs review'}: ${change}`);
|
|
259
|
+
console.log(`${result.files} file(s) checked against ${relative}: ${result.violations.length} violation(s), ${result.excepted.length} by exception${base ? `, ${contractChanges.length} contract change(s) since ${base}${unreviewed ? ' not reviewed' : ''}` : ''}`);
|
|
260
|
+
if (unreviewed) console.log('A loosened contract is a decision for the owner of these rules: get it reviewed, then run with --approved-by NAME to record who approved it. Do not edit the contract to make a check pass.');
|
|
261
|
+
}
|
|
262
|
+
return result.violations.length || unreviewed ? 1 : 0;
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('check-boundaries.mjs')) {
|
|
266
|
+
main(process.argv.slice(2)).then(code => { process.exitCode = code; }, error => {
|
|
267
|
+
console.error(error instanceof ContractError ? `check-boundaries: ${error.message}` : error);
|
|
268
|
+
process.exitCode = 2;
|
|
269
|
+
});
|
|
270
|
+
}
|
|
@@ -1,36 +1,36 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: goal-griller
|
|
3
|
-
description:
|
|
3
|
+
description: Biến một yêu cầu chưa đủ rõ của người dùng thành một task contract kiểm chứng được. Dùng khi main tiếp nhận yêu cầu mà việc thiếu kết quả mong muốn, phạm vi hay bằng chứng nghiệm thu sẽ làm đổi cách thực thi một cách đáng kể; bỏ qua khi yêu cầu đã rõ.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Làm rõ kết quả cần đạt
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
lead
|
|
10
|
-
|
|
8
|
+
Skill này phục vụ người sở hữu đầu tiếp xúc với người dùng. Trong quy trình khởi đầu đó
|
|
9
|
+
là main; lead và peer trả các quyết định còn thiếu về cho agent giao việc chứ không tự mở
|
|
10
|
+
một cuộc trao đổi riêng với người dùng.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
12
|
+
Đọc yêu cầu, các quyết định đã có, ALP.md, và vài artifact cục bộ liên quan. Tách kết quả
|
|
13
|
+
mong muốn ra khỏi implementation được gợi ý. Hãy xác lập:
|
|
14
14
|
|
|
15
|
-
- Outcome:
|
|
16
|
-
- Evidence:
|
|
17
|
-
- Scope:
|
|
18
|
-
- Context:
|
|
19
|
-
- Verification:
|
|
20
|
-
- Completion/blockers:
|
|
15
|
+
- Outcome: trạng thái quan sát được mà người dùng muốn.
|
|
16
|
+
- Evidence: một phép kiểm, artifact hay phép đo cho thấy kết quả đó.
|
|
17
|
+
- Scope: cái gì được phép đổi và cái gì người dùng yêu cầu giữ nguyên.
|
|
18
|
+
- Context: các nguồn cần có để ra quyết định đầu tiên.
|
|
19
|
+
- Verification: một vòng phản hồi nhanh và các phép kiểm cuối nếu có.
|
|
20
|
+
- Completion/blockers: khi nào công việc xong và cái gì cần một quyết định của người dùng.
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
22
|
+
Hãy suy ra các chi tiết thường lệ từ repository và từ thẩm quy���n đã có. Chỉ hỏi những câu
|
|
23
|
+
mà câu trả lời làm đổi phạm vi, hành vi, chi phí, hay một quyết định có hệ quả.
|
|
24
|
+
Gộp các câu hỏi độc lập lại cho gọn và đưa ra một mặc định hợp lý ở chỗ hữu ích.
|
|
25
|
+
Vẫn tiếp tục công việc độc lập đã được cấp quyền trong lúc chờ; thời gian trôi qua không
|
|
26
|
+
sinh ra câu trả lời bắt buộc.
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
"production
|
|
30
|
-
|
|
31
|
-
|
|
28
|
+
Đừng cử một người đi nghiên cứu để tự bịa ra nghĩa của những chữ như "tốt hơn" hay
|
|
29
|
+
"sẵn sàng cho production" khi chính kết quả cần đạt phải do người dùng phán xét. Ngược lại,
|
|
30
|
+
đừng bắt người dùng chỉ ra một câu lệnh build hay một đường dẫn file mà bằng chứng cục bộ
|
|
31
|
+
xác lập được.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
Hãy làm ra một contract tương xứng, ví dụ:
|
|
34
34
|
|
|
35
35
|
```text
|
|
36
36
|
Outcome: observable result
|
|
@@ -43,7 +43,7 @@ Done: completion condition
|
|
|
43
43
|
Blocked if: material missing decision or prerequisite
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
46
|
+
Với một task đã được cấp quyền, một contract rõ ràng là đủ để tiến hành; skill này không
|
|
47
|
+
thêm cổng duyệt nào. Nếu chỉ được yêu cầu soạn một contract, hãy trả nó về mà không bắt
|
|
48
|
+
đầu hiện thực. Chuyển một task nhiều mục sang sequence-execution-plan, hoặc một việc được
|
|
49
|
+
giao đơn lẻ sang prompt-leverage, và chỉ đọc skill kế tiếp khi cần.
|
|
@@ -1,37 +1,39 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: prompt-leverage
|
|
3
|
-
description:
|
|
3
|
+
description: Chuyển một task thành một brief giao việc tự chứa, không làm đổi ý định của người dùng và không định sẵn giải pháp. Dùng trước khi main giao cho lead hoặc lead giao cho peer, hoặc khi được yêu cầu làm tốt hơn một prompt thực thi.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Soạn một brief làm được việc
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
Xác định kết quả được yêu cầu và trách nhiệm của người nhận. Giữ nguyên các ràng buộc thật
|
|
9
|
+
sự của người dùng, nhưng phân biệt chúng với các lựa chọn thiết kế hiện tại mà người nhận
|
|
10
|
+
có quyền chất vấn. Đừng gieo trước verdict cho một reviewer, và đừng biến một implementation
|
|
11
|
+
mình thích thành một yêu cầu bịa ra.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
13
|
+
Một brief hữu ích cung cấp root, kết quả cần đạt, context liên quan, đường dẫn sở hữu/bị loại,
|
|
14
|
+
thẩm quyền, các phụ thuộc quan trọng, tài nguyên, kiểm chứng, và handoff mong đợi.
|
|
15
|
+
Dùng [định dạng brief](references/brief-template.md) cho các việc được giao có khối lượng đáng kể;
|
|
16
|
+
gộp các field lại với một task nhỏ. Một base SHA thật thì hữu ích trong một repository Git
|
|
17
|
+
nhưng không bắt buộc với một project chỉ gồm file thường. Đừng bao giờ bịa ra một cái.
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
Phần kiểm chứng phải mô tả hành vi quan sát được và, khi đã biết, cả phép kiểm chạy được của
|
|
20
|
+
nó. Nếu còn phải đi tìm câu lệnh, hãy nói rõ nên xác lập nó từ repository bằng cách nào. Đừng
|
|
21
|
+
bịa ra một câu lệnh test chỉ để điền cho đủ field.
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
smart-commits.
|
|
26
|
-
|
|
23
|
+
Chọn skill đã cài phù hợp theo loại việc và nêu tên nó trong brief:
|
|
24
|
+
nghiên cứu -> xia; chẩn đoán/regression -> bug-loop; một handoff có quyền commit ->
|
|
25
|
+
smart-commits. Đừng đòi những skill không có trong gói của người nhận. Một reviewer có thể
|
|
26
|
+
xem xét một bản ứng viên đang có mà không cần thêm nghi thức skill nào.
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
28
|
+
Gửi toàn bộ brief qua tool giao việc mà runtime của bạn thật sự cung cấp, cho một agent đã được
|
|
29
|
+
cấp quyền. Cách chọn model và effort cho người nhận, và việc có phải chọn hay không, lấy từ
|
|
30
|
+
instruction runtime của bạn (model profile của người nhận, catalog của runtime); đừng giả định
|
|
31
|
+
người nhận chạy trên model của bạn. Yêu cầu chỉ đọc cho việc nghiên cứu/review ở chỗ phù hợp.
|
|
32
|
+
Việc hiện thực cần workspace-write ở cả cha và con. Việc giao có thể chạy nền và trả kết quả
|
|
33
|
+
về sau; người nhận có thể hỏi lại hoặc không, tuỳ kênh mà runtime có. Vì vậy hãy đưa vào brief
|
|
34
|
+
mọi thứ cần thiết để làm xong việc mà không phải hỏi lại.
|
|
33
35
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
36
|
+
Skill này không cấp thẩm quyền mới nào và không bao giờ lách đồ thị định tuyến đã cấu hình. Nếu
|
|
37
|
+
chỉ được yêu cầu làm tốt hơn một prompt, hãy trả prompt về. Nếu việc giao đã được cấp quyền,
|
|
38
|
+
hãy gửi nó bằng tool thật của runtime sau khi soạn xong. Những năng lực còn thiếu phải được báo
|
|
39
|
+
cáo, không phải giả lập ra.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Định dạng brief và handoff
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Dùng đủ chi tiết để một người làm độc lập có thể làm việc hiệu quả, mà không áp đặt một giải
|
|
4
|
+
pháp chưa được kiểm chứng. Context có sẵn gồm ALP.md và hướng dẫn riêng của agent được chọn;
|
|
5
|
+
toàn bộ transcript của agent cha thì không tự động có.
|
|
6
6
|
|
|
7
7
|
```text
|
|
8
8
|
Task and recipient:
|
|
@@ -20,8 +20,8 @@ Candidate/base revision, if applicable:
|
|
|
20
20
|
Return: outcome, artifact, scope, actual checks/results, risks, ownership status.
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
23
|
+
Với review chỉ đọc, hãy cấp bản ứng viên/artifact và các tiêu chí nghiệm thu độc lập. Với một
|
|
24
|
+
bản sửa, hãy đưa kèm phát hiện cụ thể và bằng chứng trước đó. Với một việc được giao làm tiếp,
|
|
25
|
+
hãy đưa kèm các phát hiện cần thiết từ handoff trước, vì agent con kế tiếp là một phiên mới.
|
|
26
|
+
Người nhận bị chặn thì nên trả về chỗ chặn của mình cùng phần việc độc lập đã làm xong, chứ
|
|
27
|
+
đừng ngồi chờ một hộp thư không tồn tại.
|