@elvis1513/auto-coding-skill 4.1.0 → 4.1.2
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 +48 -8
- package/cli/assets/skill/SKILL.md +47 -125
- package/cli/assets/skill/data/contracts/orchestration-v1.schema.json +22 -1
- package/cli/assets/skill/data/policies/workflow-migrations-v1.json +2 -2
- package/cli/assets/skill/data/templates/ENGINEERING.md +38 -159
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +102 -114
- package/cli/assets/skill/scripts/ap.py +363 -40
- package/cli/assets/skill/scripts/core.py +21 -5
- package/cli/src/check-package.js +38 -0
- package/cli/src/index.js +20 -0
- package/cli/tests/ap_concurrency_test.py +39 -1
- package/cli/tests/ap_profiles_test.py +113 -3
- package/cli/tests/index.test.js +34 -18
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -9,7 +9,9 @@ The Skill is a selectable guardrail, not a command sequence that must run for
|
|
|
9
9
|
every task. The model skips machinery whose expected benefit does not exceed its
|
|
10
10
|
cost; read-only work and obvious small clean-checkout changes normally stay direct.
|
|
11
11
|
|
|
12
|
-
Version 4.1
|
|
12
|
+
Version 4.1.2 makes the workflow decision explicit: mechanisms are required,
|
|
13
|
+
model-selectable when beneficial, or forbidden for the current task. Version
|
|
14
|
+
4.1.1 consolidated the 4.x delivery-first workflow into one canonical
|
|
13
15
|
repository contract. Version 4.0 replaced the 3.x governance-first defaults with progressive
|
|
14
16
|
guardrails. Clean single-writer work stays on the current branch. Worktrees,
|
|
15
17
|
parallel fixers, fingerprint review, durable design records, and stronger
|
|
@@ -65,21 +67,27 @@ The result includes:
|
|
|
65
67
|
- `execution_mode=isolated`: dirty checkout, explicit isolation, or multiple writers.
|
|
66
68
|
- `execution_mode=none`: no task signal or change; create no branch/worktree.
|
|
67
69
|
- `review_required` and `design_required`: risk-based escalation decisions.
|
|
70
|
+
- `task_kind`: `read_only`, `change`, `terminal_maintenance`, or `none`.
|
|
71
|
+
- `mechanism_plan.required`: the complete minimum mechanism set for the task.
|
|
72
|
+
- `mechanism_plan.optional_when_beneficial`: model-selectable mechanisms whose
|
|
73
|
+
expected benefit must exceed coordination cost.
|
|
74
|
+
- `mechanism_plan.forbidden`: mechanisms that stay off unless the user overrides.
|
|
68
75
|
- an adaptive agent plan that does not force fan-out for ordinary work.
|
|
69
76
|
|
|
70
|
-
|
|
77
|
+
Clean serial work proceeds directly on the current branch with normal Git; it does
|
|
78
|
+
not create machine lifecycle state. Use `task-start` only when classification
|
|
79
|
+
requires isolation/review or the user explicitly requests lifecycle tracking:
|
|
71
80
|
|
|
72
81
|
```bash
|
|
73
82
|
python3 docs/tools/autopipeline/ap.py task-start T0001 \
|
|
74
|
-
--owned-path backend/internal/orders
|
|
83
|
+
--owned-path backend/internal/orders --force-lifecycle
|
|
75
84
|
python3 docs/tools/autopipeline/ap.py commit-push T0001 \
|
|
76
85
|
--msg "T0001: fix order retry"
|
|
77
86
|
```
|
|
78
87
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
If no diff was produced, it clears the manifest without commit or push.
|
|
88
|
+
When a required review still uses the current clean checkout, `task-start` records
|
|
89
|
+
a direct manifest without creating a branch/worktree. If no diff is produced,
|
|
90
|
+
closure clears the manifest without commit or push.
|
|
83
91
|
|
|
84
92
|
Dirty or parallel work receives an isolated task branch/worktree:
|
|
85
93
|
|
|
@@ -87,8 +95,9 @@ Dirty or parallel work receives an isolated task branch/worktree:
|
|
|
87
95
|
python3 docs/tools/autopipeline/ap.py task-start T0002 \
|
|
88
96
|
--owned-path backend --review-required
|
|
89
97
|
# implement in the printed worktree
|
|
98
|
+
python3 docs/tools/autopipeline/ap.py task-status T0002 --json
|
|
90
99
|
python3 docs/tools/autopipeline/ap.py task-review T0002 \
|
|
91
|
-
--verdict approved --diff-fingerprint "$
|
|
100
|
+
--verdict approved --diff-fingerprint "$CURRENT_DIFF_FINGERPRINT"
|
|
92
101
|
python3 docs/tools/autopipeline/ap.py commit-push T0002 \
|
|
93
102
|
--msg "T0002: bounded change"
|
|
94
103
|
python3 docs/tools/autopipeline/ap.py task-integrate T0002
|
|
@@ -113,10 +122,13 @@ commands:
|
|
|
113
122
|
|
|
114
123
|
validation:
|
|
115
124
|
on_unmapped: error
|
|
125
|
+
max_command_seconds: 120
|
|
126
|
+
max_total_seconds: 180
|
|
116
127
|
routes:
|
|
117
128
|
- name: backend
|
|
118
129
|
paths: ["backend/**", "contracts/**"]
|
|
119
130
|
commands: [backend_fast]
|
|
131
|
+
timeout_seconds: 90
|
|
120
132
|
- name: frontend
|
|
121
133
|
paths: ["frontend/**"]
|
|
122
134
|
commands: [frontend_fast]
|
|
@@ -147,6 +159,11 @@ closure gate is limited to one stable-diff run. Full regression, Docker, builds,
|
|
|
147
159
|
Jenkins, deployment, API verification, and target checks remain explicit
|
|
148
160
|
diagnostics outside normal closure.
|
|
149
161
|
|
|
162
|
+
The recommended final closure defaults are 120 seconds per command and 180
|
|
163
|
+
seconds total. Projects may raise them for measured affected-scope checks or set
|
|
164
|
+
a smaller `timeout_seconds` on a route. A timeout calls for a narrower route and
|
|
165
|
+
never triggers a broader fallback.
|
|
166
|
+
|
|
150
167
|
## Risk and subagent policy
|
|
151
168
|
|
|
152
169
|
- Micro and standard work default to the main agent.
|
|
@@ -183,6 +200,29 @@ project-specific facts outside the managed ENGINEERING block. Root `AGENTS.md` i
|
|
|
183
200
|
replaced as a whole; its previous content is archived under
|
|
184
201
|
`docs/archive/workflow/` as historical, non-authoritative context.
|
|
185
202
|
|
|
203
|
+
## What changed in 4.1.2
|
|
204
|
+
|
|
205
|
+
- Added explicit read-only, change, and terminal-maintenance task kinds so
|
|
206
|
+
intent-only questions cannot accidentally trigger code-delivery machinery.
|
|
207
|
+
- Split mechanism planning into required, model-selectable, and forbidden sets;
|
|
208
|
+
read-only discovery agents remain available when they save time or add needed
|
|
209
|
+
expertise.
|
|
210
|
+
- Made 120/180-second gate budgets recommended defaults, added route-level
|
|
211
|
+
timeouts, and kept project-specific affected-scope overrides valid.
|
|
212
|
+
- Rejected unnecessary lifecycle creation before access checks, fetching, locks,
|
|
213
|
+
or branch work; corrected the review lifecycle examples.
|
|
214
|
+
- Added a release-package assertion and prepack cache cleanup so generated Python
|
|
215
|
+
caches cannot leak into the npm tarball.
|
|
216
|
+
|
|
217
|
+
## What changed in 4.1.1
|
|
218
|
+
|
|
219
|
+
- Added a machine-readable minimum mechanism plan and rejected unnecessary clean
|
|
220
|
+
serial task lifecycles unless explicitly requested.
|
|
221
|
+
- Added bounded per-command and total time budgets for the final changed-scope gate.
|
|
222
|
+
- Made root `AGENTS.md` the sole behavioral protocol, reduced `SKILL.md` to
|
|
223
|
+
invocation guidance, and reduced `ENGINEERING.md` to project configuration and
|
|
224
|
+
facts.
|
|
225
|
+
|
|
186
226
|
## What changed in 4.1.0
|
|
187
227
|
|
|
188
228
|
- Made root `AGENTS.md` byte-identical across installed projects and whole-file
|
|
@@ -1,154 +1,80 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: auto-coding-skill
|
|
3
|
-
description:
|
|
3
|
+
description: Optional delivery-first engineering workflow for repository changes. Use when its bounded validation, adaptive Git isolation, review, or coordination will improve delivery speed or defect prevention. Keep clean serial work on the current branch and let the model select beneficial design or subagents without turning them into mandatory ceremony.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Auto Coding Skill
|
|
7
7
|
|
|
8
|
-
##
|
|
8
|
+
## Use the two authorities
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
need no classify command, machine task lifecycle, design record, reviewer, or
|
|
14
|
-
subagent by default. Repository code changes still receive one real, fast,
|
|
15
|
-
affected-scope validation before commit/push.
|
|
10
|
+
Read root `AGENTS.md` for the shared behavioral protocol and
|
|
11
|
+
`docs/ENGINEERING.md` for project facts, access, risk, validation, and budgets.
|
|
12
|
+
Do not reconstruct or duplicate those rules from historical task documents.
|
|
16
13
|
|
|
17
|
-
|
|
14
|
+
Normal delivery is:
|
|
18
15
|
|
|
19
|
-
`analysis → decomposition → necessary design → development → one final
|
|
16
|
+
`analysis → decomposition → necessary design → development → one bounded final
|
|
20
17
|
changed-scope gate → commit/push`.
|
|
21
18
|
|
|
22
|
-
|
|
23
|
-
facts, access values, risk rules, and validation routes. Treat target-branch push
|
|
24
|
-
as normal coding completion. Do not poll Jenkins, deployment, or owner acceptance.
|
|
25
|
-
When the user explicitly asks to diagnose a failure caused by that push, continue
|
|
26
|
-
the diagnosis and repair in the same conversation/task without inventing another
|
|
27
|
-
ledger lifecycle.
|
|
19
|
+
## Select the minimum mechanism set
|
|
28
20
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
- Use the current branch for one writer when the checkout is clean.
|
|
34
|
-
- Use an isolated task branch/worktree when unrelated changes already exist,
|
|
35
|
-
when more than one writer will run, or when the project explicitly requires it.
|
|
36
|
-
- Use one writer per worktree and non-overlapping owned paths.
|
|
37
|
-
- Create no temporary branch merely to analyze a task or when no diff is produced.
|
|
38
|
-
- Never restore, reset, stash, clean, or modify unknown user/task changes.
|
|
39
|
-
|
|
40
|
-
Classify planned work before development when impact is unclear:
|
|
21
|
+
Read-only questions need no workflow command. Obvious clean serial edits and
|
|
22
|
+
terminal ledger maintenance may follow root `AGENTS.md` directly. When task kind,
|
|
23
|
+
impact, risk, or concurrency is unclear, run:
|
|
41
24
|
|
|
42
25
|
```bash
|
|
43
26
|
python3 docs/tools/autopipeline/ap.py classify --scope auto \
|
|
44
|
-
--planned-path <PATH> --intent "<intent>" [--writers <N>]
|
|
27
|
+
--planned-path <PATH> --intent "<intent>" [--writers <N>] \
|
|
28
|
+
[--task-kind read_only|change|terminal_maintenance]
|
|
45
29
|
```
|
|
46
30
|
|
|
47
|
-
`
|
|
48
|
-
`
|
|
49
|
-
|
|
31
|
+
Run `mechanism_plan.required`. The model may select
|
|
32
|
+
`optional_when_beneficial` only when expected value exceeds coordination cost.
|
|
33
|
+
Do not run `forbidden` mechanisms unless the user explicitly overrides the plan.
|
|
34
|
+
Reclassify only when task kind, scope, risk, or writer count materially changes.
|
|
35
|
+
Ordinary direct work does not create a task lifecycle.
|
|
50
36
|
|
|
51
|
-
Use the
|
|
37
|
+
Use the registered lifecycle only when classification requires isolation or
|
|
38
|
+
fingerprinted review, or when the user explicitly requests it:
|
|
52
39
|
|
|
53
40
|
```bash
|
|
54
41
|
python3 docs/tools/autopipeline/ap.py task-start T0001 \
|
|
55
|
-
--owned-path src [--isolated] [--review-required]
|
|
56
|
-
#
|
|
42
|
+
--owned-path src [--isolated] [--review-required] [--force-lifecycle]
|
|
43
|
+
# For review-required work, obtain the current fingerprint and approve it:
|
|
44
|
+
python3 docs/tools/autopipeline/ap.py task-status T0001 --json
|
|
45
|
+
python3 docs/tools/autopipeline/ap.py task-review T0001 \
|
|
46
|
+
--verdict approved --diff-fingerprint <CURRENT_DIFF_FINGERPRINT>
|
|
57
47
|
python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
|
|
58
48
|
# Isolated tasks only:
|
|
59
49
|
python3 docs/tools/autopipeline/ap.py task-integrate T0001
|
|
60
50
|
```
|
|
61
51
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
## Scale design and review by risk
|
|
69
|
-
|
|
70
|
-
Use `micro`, `standard`, and `high-risk` only to scale reasoning and guardrails;
|
|
71
|
-
never use them to trigger a full local repository gate automatically.
|
|
72
|
-
|
|
73
|
-
- Keep ordinary micro/standard work main-agent-only unless delegation has a
|
|
74
|
-
concrete latency or expertise benefit.
|
|
75
|
-
- Create DD/ADR only for lasting cross-module, API, data, security, deployment,
|
|
76
|
-
or key user-flow decisions.
|
|
77
|
-
- Require independent fingerprinted review for high-risk, cross-module,
|
|
78
|
-
explicitly configured, or parallel integration work.
|
|
79
|
-
- Route blocking review findings back to the owning writer and invalidate the
|
|
80
|
-
approval after any content change or rebase.
|
|
81
|
-
- Keep review inside the promised task scope. Adjacent pre-existing findings are
|
|
82
|
-
non-blocking follow-ups. Semantic changes require full review against a new
|
|
83
|
-
fingerprint; mechanical docs-only corrections may use a targeted recheck.
|
|
84
|
-
|
|
85
|
-
Historical debt does not block normal delivery. Block only new or worsened P0/P1
|
|
86
|
-
issues. Handle repository-wide governance through an explicit task and optional
|
|
87
|
-
baseline/backlog.
|
|
88
|
-
|
|
89
|
-
## Use subagents when they improve throughput
|
|
90
|
-
|
|
91
|
-
Let the main agent own decomposition, architecture, dependencies, final gate,
|
|
92
|
-
Git closure, integration, and cleanup.
|
|
93
|
-
|
|
94
|
-
- Run independent read-only explorer, docs, or browser questions in parallel only
|
|
95
|
-
when the model judges their expected value higher than coordination cost;
|
|
96
|
-
classification may suggest capabilities but never auto-dispatches them.
|
|
97
|
-
- Dispatch fixers only for bounded, dependency-free units with non-overlapping
|
|
98
|
-
paths; give each parallel fixer its own task ID, writer lease, and registered
|
|
99
|
-
worktree. `task-start` creates exactly one writer/worktree.
|
|
100
|
-
- Start dependent writers only after prerequisite commits are integrated.
|
|
101
|
-
- Add a reviewer only when the risk policy requires one.
|
|
102
|
-
- Do not force fan-out for small serial tasks.
|
|
103
|
-
|
|
104
|
-
Subagents do not commit, push, integrate, clean branches, or run the final project
|
|
105
|
-
gate. Use the bundled orchestration contract when structured assignments/results
|
|
106
|
-
are useful; ordinary main-agent work needs no task ledger.
|
|
107
|
-
|
|
108
|
-
## Run real changed-scope validation
|
|
109
|
-
|
|
110
|
-
Keep classification under `risk.rules` and executable checks under
|
|
111
|
-
`validation.routes`. Match every changed path against all routes, collect command
|
|
112
|
-
references in configuration order, remove duplicates, and run each once.
|
|
52
|
+
Each parallel writer uses a distinct task ID, registered worktree, writer lease,
|
|
53
|
+
dependency SHAs, and non-overlapping `owned_paths`. The main agent alone runs the
|
|
54
|
+
final gate, integrates, pushes, and cleans safely merged temporary branches.
|
|
55
|
+
|
|
56
|
+
## Close with the bounded routed gate
|
|
113
57
|
|
|
114
58
|
```bash
|
|
115
59
|
python3 docs/tools/autopipeline/ap.py validation-map-check --path <PATH>
|
|
116
60
|
python3 docs/tools/autopipeline/ap.py light-gate --scope changed --explain
|
|
117
61
|
```
|
|
118
62
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
dependencies, and review fingerprints in the Git common directory. Store gate
|
|
135
|
-
timing/evidence under `.local` by default.
|
|
136
|
-
Do not create taskbook, closure Markdown, evidence JSONL, active-task, or design
|
|
137
|
-
documents for ordinary work. Preserve existing project documents as user data;
|
|
138
|
-
create or update them only when explicitly useful.
|
|
139
|
-
|
|
140
|
-
Keep root `AGENTS.md` byte-identical to the packaged canonical file; sync replaces
|
|
141
|
-
it as a whole and archives its previous contents as historical, non-authoritative
|
|
142
|
-
context. Keep `docs/ENGINEERING.md` as the only manual workflow configuration
|
|
143
|
-
source. Put larger product, repository, and runtime facts in `docs/project/`, not
|
|
144
|
-
in root AGENTS or duplicated workflow sections. Allow direct plaintext values
|
|
145
|
-
under `access.*`; do not invent or echo credentials.
|
|
146
|
-
|
|
147
|
-
Pure ledger, closure, or archive reconciliation is a terminal maintenance action:
|
|
148
|
-
run its targeted consistency check and commit once. It must not create another
|
|
149
|
-
active task, closure record, evidence chain, or review cycle for closing itself.
|
|
150
|
-
|
|
151
|
-
## Install and upgrade
|
|
63
|
+
Every changed code/config path must map to a real project command. The runtime
|
|
64
|
+
de-duplicates commands and enforces route, command, and total budgets. Defaults
|
|
65
|
+
are 120 seconds per command and 180 total; projects may raise them for a measured
|
|
66
|
+
affected-scope check. Timeouts should narrow the route, never trigger a full build.
|
|
67
|
+
Focused test/fix/retest loops remain allowed before the final gate.
|
|
68
|
+
|
|
69
|
+
Run full regression, Docker, Jenkins, deployment, browser/device writes, or target
|
|
70
|
+
acceptance only as an explicit diagnostic. A requested just-pushed failure
|
|
71
|
+
diagnosis continues in the same task without inventing another lifecycle.
|
|
72
|
+
|
|
73
|
+
## Keep state and upgrades safe
|
|
74
|
+
|
|
75
|
+
Machine task state, leases, fingerprints, and gate evidence stay in Git local
|
|
76
|
+
state. Ordinary work creates no taskbook, closure, evidence JSONL, active-task,
|
|
77
|
+
or design artifact. Terminal ledger reconciliation validates and commits once.
|
|
152
78
|
|
|
153
79
|
```bash
|
|
154
80
|
autocoding init
|
|
@@ -158,9 +84,5 @@ python3 docs/tools/autopipeline/ap.py upgrade --write
|
|
|
158
84
|
python3 docs/tools/autopipeline/ap.py doctor
|
|
159
85
|
```
|
|
160
86
|
|
|
161
|
-
Finish
|
|
162
|
-
|
|
163
|
-
documents, and explicit model overrides while removing obsolete managed Skill
|
|
164
|
-
files and filling new managed assets. Root `AGENTS.md` is the exception: it is
|
|
165
|
-
fully replaced by the canonical version, with the previous file archived under
|
|
166
|
-
`docs/archive/workflow/`.
|
|
87
|
+
Finish registered tasks before changing versions. Sync replaces root `AGENTS.md`,
|
|
88
|
+
archives it, preserves project facts/access, and converges all managed assets.
|
|
@@ -11,6 +11,19 @@
|
|
|
11
11
|
"type": "string"
|
|
12
12
|
}
|
|
13
13
|
},
|
|
14
|
+
"mechanismPlan": {
|
|
15
|
+
"type": "object",
|
|
16
|
+
"required": ["required", "optional_when_beneficial", "forbidden", "not_required", "lifecycle_required", "rule"],
|
|
17
|
+
"properties": {
|
|
18
|
+
"required": { "$ref": "#/$defs/stringArray" },
|
|
19
|
+
"optional_when_beneficial": { "$ref": "#/$defs/stringArray" },
|
|
20
|
+
"forbidden": { "$ref": "#/$defs/stringArray" },
|
|
21
|
+
"not_required": { "$ref": "#/$defs/stringArray" },
|
|
22
|
+
"lifecycle_required": { "type": "boolean" },
|
|
23
|
+
"rule": { "type": "string", "minLength": 1 }
|
|
24
|
+
},
|
|
25
|
+
"additionalProperties": false
|
|
26
|
+
},
|
|
14
27
|
"fingerprint": {
|
|
15
28
|
"type": "string",
|
|
16
29
|
"pattern": "^$|^[0-9a-f]{64}$"
|
|
@@ -441,10 +454,12 @@
|
|
|
441
454
|
"classification_files",
|
|
442
455
|
"intent_provided",
|
|
443
456
|
"intent_categories",
|
|
457
|
+
"task_kind",
|
|
444
458
|
"profile",
|
|
445
459
|
"categories",
|
|
446
460
|
"recommended_agents",
|
|
447
|
-
"agent_plan"
|
|
461
|
+
"agent_plan",
|
|
462
|
+
"mechanism_plan"
|
|
448
463
|
],
|
|
449
464
|
"properties": {
|
|
450
465
|
"contract_version": {
|
|
@@ -468,6 +483,9 @@
|
|
|
468
483
|
"intent_categories": {
|
|
469
484
|
"$ref": "#/$defs/stringArray"
|
|
470
485
|
},
|
|
486
|
+
"task_kind": {
|
|
487
|
+
"enum": ["none", "read_only", "change", "terminal_maintenance"]
|
|
488
|
+
},
|
|
471
489
|
"profile": {
|
|
472
490
|
"enum": [
|
|
473
491
|
"micro",
|
|
@@ -483,6 +501,9 @@
|
|
|
483
501
|
},
|
|
484
502
|
"agent_plan": {
|
|
485
503
|
"$ref": "#/$defs/agentPlan"
|
|
504
|
+
},
|
|
505
|
+
"mechanism_plan": {
|
|
506
|
+
"$ref": "#/$defs/mechanismPlan"
|
|
486
507
|
}
|
|
487
508
|
},
|
|
488
509
|
"additionalProperties": true
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
workflow:
|
|
3
|
-
skill_version: "4.1.
|
|
3
|
+
skill_version: "4.1.2"
|
|
4
4
|
mode: "dev"
|
|
5
5
|
profile: "auto"
|
|
6
6
|
completion: "push"
|
|
@@ -50,15 +50,18 @@ concurrency:
|
|
|
50
50
|
disposable_ignored: []
|
|
51
51
|
|
|
52
52
|
commands:
|
|
53
|
-
# Optional convenience command.
|
|
54
|
-
#
|
|
55
|
-
# when package.json declares `test:changed`.
|
|
53
|
+
# Optional convenience command. Define the project-native fast commands used
|
|
54
|
+
# by validation.routes; sync fills this only for package.json test:changed.
|
|
56
55
|
project_fast: ""
|
|
57
56
|
|
|
58
57
|
validation:
|
|
59
58
|
on_unmapped: "error"
|
|
60
|
-
#
|
|
61
|
-
#
|
|
59
|
+
# Recommended fast defaults. Raise only for a measured affected-scope check;
|
|
60
|
+
# an individual route may set a smaller timeout_seconds.
|
|
61
|
+
max_command_seconds: 120
|
|
62
|
+
max_total_seconds: 180
|
|
63
|
+
# Initialization must replace this with real path-to-command mappings. Empty
|
|
64
|
+
# routes intentionally fail closed for code/config changes.
|
|
62
65
|
routes: []
|
|
63
66
|
|
|
64
67
|
risk:
|
|
@@ -89,169 +92,45 @@ docs:
|
|
|
89
92
|
api_change_log: "docs/interfaces/api-change-log.md"
|
|
90
93
|
---
|
|
91
94
|
|
|
92
|
-
# Engineering
|
|
95
|
+
# Engineering Configuration and Project Facts
|
|
93
96
|
|
|
94
|
-
<!-- auto-coding-skill:managed-workflow:start version=4.1.
|
|
97
|
+
<!-- auto-coding-skill:managed-workflow:start version=4.1.2 -->
|
|
95
98
|
|
|
96
|
-
|
|
97
|
-
|
|
99
|
+
Root `AGENTS.md` is the single shared behavioral protocol. The installed
|
|
100
|
+
`SKILL.md` contains invocation guidance. This file is the single source for the
|
|
101
|
+
project-specific configuration and facts that neither file can infer.
|
|
98
102
|
|
|
99
|
-
|
|
100
|
-
changed-scope gate → commit/push`.
|
|
103
|
+
The frontmatter contract is:
|
|
101
104
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
105
|
+
- `workflow`: installed version and push-completion mode.
|
|
106
|
+
- `access`: required project, Jenkins, GitLab, and Nexus access values.
|
|
107
|
+
- `concurrency`: target branch and adaptive isolation settings.
|
|
108
|
+
- `commands`: project-native executable commands.
|
|
109
|
+
- `validation`: explicit path-to-command routes plus the bounded final-gate time
|
|
110
|
+
budget. Code/config paths must be mapped; route-level `timeout_seconds` can
|
|
111
|
+
bound a slower command without changing the project defaults.
|
|
112
|
+
- `risk`: project-specific signals that increase design/review depth but never
|
|
113
|
+
expand the automatic local gate.
|
|
114
|
+
- `structure` and `optimization`: advisory architecture and no-new-debt policy.
|
|
115
|
+
- `docs`: locations of optional durable project artifacts.
|
|
106
116
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
reviewer, and subagents. Use each mechanism only when its expected quality or
|
|
111
|
-
throughput benefit is greater than its coordination cost.
|
|
117
|
+
Run `python3 docs/tools/autopipeline/ap.py doctor` after changing frontmatter.
|
|
118
|
+
Do not put competing delivery flows, agent roles, lifecycle rules, gate semantics,
|
|
119
|
+
or completion rules outside this managed block.
|
|
112
120
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
| Level | Default behavior | Added guardrails |
|
|
116
|
-
| --- | --- | --- |
|
|
117
|
-
| Micro | main agent, current branch, fast route | none |
|
|
118
|
-
| Standard | main agent or justified read-only help | no mandatory reviewer or design document |
|
|
119
|
-
| High risk | focused design and independent review | only the affected validation routes |
|
|
120
|
-
| Parallel | one isolated writer per unit | owned paths, dependency SHAs, leases, fingerprint review, ordered integration |
|
|
121
|
-
|
|
122
|
-
Risk changes analysis, design, and review depth. It never promotes normal local
|
|
123
|
-
development to a full repository build, Docker run, Jenkins poll, deployment, or
|
|
124
|
-
target-environment acceptance.
|
|
125
|
-
|
|
126
|
-
## Adaptive isolation
|
|
127
|
-
|
|
128
|
-
Run task planning before development:
|
|
129
|
-
|
|
130
|
-
```bash
|
|
131
|
-
python3 docs/tools/autopipeline/ap.py classify --scope auto \
|
|
132
|
-
--planned-path <PATH> --intent "<task intent>" [--writers <N>]
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
- A clean checkout with one writer uses the current branch directly.
|
|
136
|
-
- A checkout that already contains unrelated changes uses an isolated task
|
|
137
|
-
branch/worktree.
|
|
138
|
-
- Two or more concurrent writers always use separate task IDs/worktrees with
|
|
139
|
-
non-overlapping owned paths; each `task-start` creates exactly one writer lease.
|
|
140
|
-
- A task that produces no diff creates no commit or push; direct mode creates no
|
|
141
|
-
temporary branch at all.
|
|
142
|
-
- Never restore, reset, stash, clean, or otherwise modify unknown user or task
|
|
143
|
-
changes.
|
|
144
|
-
|
|
145
|
-
`task-start` implements this decision. Use `--isolated` to force a worktree and
|
|
146
|
-
`--review-required` when a project rule or the task risk requires fingerprinted
|
|
147
|
-
review:
|
|
148
|
-
|
|
149
|
-
```bash
|
|
150
|
-
python3 docs/tools/autopipeline/ap.py task-start T0001 \
|
|
151
|
-
--owned-path src --writers 1
|
|
152
|
-
python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
In direct mode, `commit-push` runs the final gate, commits, and pushes the current
|
|
156
|
-
target branch. In isolated mode it pushes the task branch; the main agent then
|
|
157
|
-
runs `task-integrate`, which pushes the target branch and removes clean merged
|
|
158
|
-
temporary branches/worktrees. `task-prune` removes only safely merged leftovers.
|
|
159
|
-
|
|
160
|
-
## Real changed-scope validation
|
|
161
|
-
|
|
162
|
-
`risk.rules` classifies work. `validation.routes` executes checks. Do not mix
|
|
163
|
-
these responsibilities.
|
|
164
|
-
|
|
165
|
-
```yaml
|
|
166
|
-
commands:
|
|
167
|
-
backend_fast: "cd backend && go test ./internal/orders/..."
|
|
168
|
-
frontend_fast: "cd frontend && npm run test:changed"
|
|
169
|
-
|
|
170
|
-
validation:
|
|
171
|
-
on_unmapped: error
|
|
172
|
-
routes:
|
|
173
|
-
- name: backend
|
|
174
|
-
paths: ["backend/**", "contracts/**"]
|
|
175
|
-
commands: [backend_fast]
|
|
176
|
-
- name: frontend
|
|
177
|
-
paths: ["frontend/**"]
|
|
178
|
-
commands: [frontend_fast]
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
Every changed path may match multiple routes. The runtime collects all commands
|
|
182
|
-
in configuration order, removes duplicates, and executes each once. Unmapped
|
|
183
|
-
code fails before staging. Documentation-only changes may use the built-in diff
|
|
184
|
-
check. `git diff --check` is always an additional hygiene check and never counts
|
|
185
|
-
as business-code validation.
|
|
186
|
-
|
|
187
|
-
Inspect coverage without running the commands:
|
|
188
|
-
|
|
189
|
-
```bash
|
|
190
|
-
python3 docs/tools/autopipeline/ap.py validation-map-check --path backend/foo.go
|
|
191
|
-
python3 docs/tools/autopipeline/ap.py validation-map-check --tracked
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
Focused tests may be run and rerun during implementation. The "one gate" rule
|
|
195
|
-
means one final routed closure gate after the diff is stable; it does not prohibit
|
|
196
|
-
reasonable test/fix/retest cycles. Do not install dependencies proactively. Only
|
|
197
|
-
after the selected final route fails because a repository-locked dependency is
|
|
198
|
-
absent may it be restored once; then retry only that affected route.
|
|
199
|
-
|
|
200
|
-
## Design, review, and subagents
|
|
201
|
-
|
|
202
|
-
- Create DD/ADR only for lasting cross-module, API, data, security, deployment,
|
|
203
|
-
or key user-flow decisions.
|
|
204
|
-
- Ordinary work defaults to the main agent. Delegate only independent discovery
|
|
205
|
-
or implementation units whose latency or expertise benefit exceeds dispatch
|
|
206
|
-
cost.
|
|
207
|
-
- Read-only explorer/docs/browser roles may run in parallel when their questions
|
|
208
|
-
are independent.
|
|
209
|
-
- Parallel fixers require separate worktrees and non-overlapping owned paths.
|
|
210
|
-
- Require reviewer fingerprint approval for high-risk, cross-module, explicitly
|
|
211
|
-
configured, or parallel integration work; ordinary serial fixes do not require it.
|
|
212
|
-
- The main agent alone owns the final gate, commit, push, ordered integration,
|
|
213
|
-
and temporary-branch cleanup.
|
|
214
|
-
|
|
215
|
-
## Documentation framework and lightweight records
|
|
216
|
-
|
|
217
|
-
This managed block and the installed Skill define the shared workflow. Content
|
|
218
|
-
outside this block may describe project facts only: product/domain boundaries,
|
|
219
|
-
repository ownership, runtime/deployment topology, external-system safety,
|
|
220
|
-
validation commands, and links to current contracts/decisions. It must not
|
|
221
|
-
duplicate delivery levels, agent roles, task lifecycle, gate semantics, or
|
|
222
|
-
completion rules.
|
|
223
|
-
|
|
224
|
-
When project facts are too large for this file, scaffold `docs/project/` and link
|
|
225
|
-
those documents here. Code, tests, schemas, migrations, and runtime configuration
|
|
226
|
-
remain authoritative for behavior that exists now; historical records never
|
|
227
|
-
override them.
|
|
121
|
+
<!-- auto-coding-skill:managed-workflow:end -->
|
|
228
122
|
|
|
229
|
-
|
|
230
|
-
task documents. Isolated-task coordination state lives under the Git common
|
|
231
|
-
directory and gate timing lives under `.local/auto-coding-skill`. Existing project
|
|
232
|
-
ledgers are user data: upgrades preserve them but do not require or update them.
|
|
233
|
-
Use `record-closure`, documentation scaffolds, or a baseline only when the user or
|
|
234
|
-
task genuinely needs a durable artifact.
|
|
123
|
+
# Project Facts
|
|
235
124
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
create a new active task, review cycle, closure record, or evidence chain for the
|
|
239
|
-
act of closing the previous record.
|
|
125
|
+
Keep only current, project-specific facts here. Put larger material under
|
|
126
|
+
`docs/project/` and link it from the relevant section.
|
|
240
127
|
|
|
241
|
-
|
|
242
|
-
issues; keep accepted debt in an optional backlog and address it through explicit
|
|
243
|
-
governance tasks.
|
|
128
|
+
## Product and domain boundaries
|
|
244
129
|
|
|
245
|
-
##
|
|
130
|
+
## Repository and ownership map
|
|
246
131
|
|
|
247
|
-
|
|
248
|
-
initialization. Direct plaintext values are allowed. The generic workflow neither
|
|
249
|
-
forbids them nor rewrites a project's credential policy.
|
|
132
|
+
## Runtime and deployment topology
|
|
250
133
|
|
|
251
|
-
|
|
252
|
-
and deployment remain explicit diagnostic commands. Do not run or poll them
|
|
253
|
-
during normal closure. An explicitly requested diagnosis of a failure caused by
|
|
254
|
-
the just-pushed change may stay in the same conversation/task; it does not require
|
|
255
|
-
an artificial second lifecycle record.
|
|
134
|
+
## External-system and real-device safety
|
|
256
135
|
|
|
257
|
-
|
|
136
|
+
## Interface and decision links
|