universal-dev-standards 5.1.1 → 5.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.
- package/bundled/ai/options/push/single-owner-mode.ai.yaml +60 -0
- package/bundled/ai/options/push/team-mode.ai.yaml +64 -0
- package/bundled/ai/standards/agent-behavior-discipline.ai.yaml +142 -0
- package/bundled/core/agent-behavior-discipline.md +178 -0
- package/bundled/core/versioning.md +1 -1
- package/bundled/locales/zh-CN/CHANGELOG.md +23 -3
- package/bundled/locales/zh-CN/README.md +9 -1
- package/bundled/locales/zh-CN/SECURITY.md +8 -0
- package/bundled/locales/zh-CN/core/ai-friendly-architecture.md +8 -0
- package/bundled/locales/zh-CN/core/workflow-enforcement.md +8 -0
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +8 -0
- package/bundled/locales/zh-CN/docs/CLI-FLOW.md +8 -0
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +8 -0
- package/bundled/locales/zh-CN/docs/STANDARDS-REFERENCE.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/requirement.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/reverse-bdd.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/reverse-sdd.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/reverse-tdd.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/reverse.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/review.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/sdd.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/tdd.md +8 -0
- package/bundled/locales/zh-CN/skills/commands/update.md +8 -0
- package/bundled/locales/zh-TW/CHANGELOG.md +23 -3
- package/bundled/locales/zh-TW/MAINTENANCE.md +17 -6
- package/bundled/locales/zh-TW/README.md +9 -1
- package/bundled/locales/zh-TW/SECURITY.md +8 -0
- package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +1 -1
- package/bundled/locales/zh-TW/core/ai-friendly-architecture.md +8 -0
- package/bundled/locales/zh-TW/core/anti-hallucination.md +8 -0
- package/bundled/locales/zh-TW/core/git-workflow.md +8 -0
- package/bundled/locales/zh-TW/core/refactoring-standards.md +8 -0
- package/bundled/locales/zh-TW/core/spec-driven-development.md +8 -0
- package/bundled/locales/zh-TW/core/structured-task-definition.md +8 -0
- package/bundled/locales/zh-TW/core/test-driven-development.md +8 -0
- package/bundled/locales/zh-TW/core/versioning.md +1 -1
- package/bundled/locales/zh-TW/core/workflow-enforcement.md +8 -0
- package/bundled/locales/zh-TW/core/workflow-state-protocol.md +8 -0
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +8 -0
- package/bundled/locales/zh-TW/docs/CLI-FLOW.md +8 -0
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +8 -0
- package/bundled/locales/zh-TW/docs/MIGRATION-V5.md +8 -0
- package/bundled/locales/zh-TW/docs/STANDARDS-REFERENCE.md +8 -0
- package/bundled/locales/zh-TW/integrations/claude-code/README.md +8 -0
- package/bundled/skills/push/SKILL.md +203 -0
- package/package.json +1 -1
- package/src/config/ai-agent-paths.js +0 -1
- package/standards-registry.json +15 -4
- package/bundled/locales/zh-CN/docs/AI-AGENT-ROADMAP.md +0 -410
- package/bundled/locales/zh-CN/docs/OPERATION-WORKFLOW.md +0 -1074
- package/bundled/locales/zh-TW/docs/AI-AGENT-ROADMAP.md +0 -410
- package/bundled/locales/zh-TW/docs/OPERATION-WORKFLOW.md +0 -1074
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Push Option: Single Owner Mode - AI Optimized
|
|
2
|
+
# Parent: push-standards (XSPEC-081)
|
|
3
|
+
# Source: options/push/single-owner-mode.md
|
|
4
|
+
|
|
5
|
+
id: single-owner-mode
|
|
6
|
+
meta:
|
|
7
|
+
parent: push-standards
|
|
8
|
+
version: "1.0.0"
|
|
9
|
+
updated: "2026-04-24"
|
|
10
|
+
source: options/push/single-owner-mode.md
|
|
11
|
+
description: Reduced-friction push mode for personal/solo repositories — removes collaboration guardrails while keeping essential safety checks
|
|
12
|
+
|
|
13
|
+
best_for:
|
|
14
|
+
- Personal repositories with sole ownership
|
|
15
|
+
- Solo open source projects with no external contributors
|
|
16
|
+
- Forked repositories for personal experimentation
|
|
17
|
+
|
|
18
|
+
configuration:
|
|
19
|
+
repo_mode: single-owner
|
|
20
|
+
protected_branches: [main, master, "release/*", "hotfix/*"]
|
|
21
|
+
push_gates:
|
|
22
|
+
default: [lint, test]
|
|
23
|
+
receipt:
|
|
24
|
+
output: console
|
|
25
|
+
auto_pr: false
|
|
26
|
+
|
|
27
|
+
behaviors:
|
|
28
|
+
protected_branch_detection:
|
|
29
|
+
enabled: true
|
|
30
|
+
confirmation_required: false
|
|
31
|
+
action: warning_only
|
|
32
|
+
note: Shows branch name and pending commit count; user proceeds without typing confirmation string
|
|
33
|
+
|
|
34
|
+
force_push_guardrail:
|
|
35
|
+
enabled: true
|
|
36
|
+
confirmation_required: false
|
|
37
|
+
action: warning_only
|
|
38
|
+
shows: commits_count_only
|
|
39
|
+
note: No author breakdown; records force_push=true in receipt
|
|
40
|
+
|
|
41
|
+
pre_push_gates:
|
|
42
|
+
gates: [lint, test]
|
|
43
|
+
execution: sequential
|
|
44
|
+
skip_flag: "--skip-gates"
|
|
45
|
+
skip_records: gates_skipped=true
|
|
46
|
+
|
|
47
|
+
pr_automation:
|
|
48
|
+
enabled: false
|
|
49
|
+
auto_pr: false
|
|
50
|
+
note: No PR prompts after push; use 'gh pr create' manually if needed
|
|
51
|
+
|
|
52
|
+
push_receipt:
|
|
53
|
+
output: console
|
|
54
|
+
fields: [branch, commit_sha, gates_passed, gates_skipped, force_push, timestamp, target_remote]
|
|
55
|
+
|
|
56
|
+
comparison_with_team_mode:
|
|
57
|
+
protected_branch_detection: warning_only # team: full + confirmation required
|
|
58
|
+
force_push_guardrail: warning_only # team: confirmation text required
|
|
59
|
+
pre_push_gates: identical # both: lint + test
|
|
60
|
+
pr_automation: disabled # team: enabled
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Push Option: Team Mode - AI Optimized
|
|
2
|
+
# Parent: push-standards (XSPEC-081)
|
|
3
|
+
# Source: options/push/team-mode.md
|
|
4
|
+
|
|
5
|
+
id: team-mode
|
|
6
|
+
meta:
|
|
7
|
+
parent: push-standards
|
|
8
|
+
version: "1.0.0"
|
|
9
|
+
updated: "2026-04-24"
|
|
10
|
+
source: options/push/team-mode.md
|
|
11
|
+
description: Default push mode with full collaboration guardrails for multi-contributor repositories
|
|
12
|
+
|
|
13
|
+
best_for:
|
|
14
|
+
- Team projects with 2+ contributors
|
|
15
|
+
- Open source repositories accepting external contributions
|
|
16
|
+
- Projects using protected branch policies
|
|
17
|
+
- Any repository requiring code review before merge
|
|
18
|
+
|
|
19
|
+
configuration:
|
|
20
|
+
repo_mode: team
|
|
21
|
+
protected_branches: [main, master, "release/*", "hotfix/*"]
|
|
22
|
+
push_gates:
|
|
23
|
+
default: [lint, test]
|
|
24
|
+
receipt:
|
|
25
|
+
output: console
|
|
26
|
+
auto_pr: true
|
|
27
|
+
|
|
28
|
+
behaviors:
|
|
29
|
+
protected_branch_detection:
|
|
30
|
+
enabled: true
|
|
31
|
+
confirmation_required: true
|
|
32
|
+
action: full_guardrail
|
|
33
|
+
note: Displays warning banner; user must explicitly confirm before proceeding
|
|
34
|
+
|
|
35
|
+
force_push_guardrail:
|
|
36
|
+
enabled: true
|
|
37
|
+
confirmation_required: true
|
|
38
|
+
confirmation_text: "yes, force push"
|
|
39
|
+
shows: [commits_count, authors]
|
|
40
|
+
note: User must type confirmation string; records force_push=true in receipt
|
|
41
|
+
|
|
42
|
+
pre_push_gates:
|
|
43
|
+
gates: [lint, test]
|
|
44
|
+
execution: sequential
|
|
45
|
+
failure_message: includes_suggested_fix
|
|
46
|
+
skip_flag: "--skip-gates"
|
|
47
|
+
skip_records: gates_skipped=true
|
|
48
|
+
|
|
49
|
+
pr_automation:
|
|
50
|
+
enabled: true
|
|
51
|
+
trigger: push_to_non_protected_branch
|
|
52
|
+
checks_existing_pr: true
|
|
53
|
+
no_pr_action: prompt_pr_automation_assistant
|
|
54
|
+
skip_flag: "--no-pr"
|
|
55
|
+
|
|
56
|
+
push_receipt:
|
|
57
|
+
output: console
|
|
58
|
+
fields: [branch, commit_sha, gates_passed, gates_skipped, force_push, timestamp, target_remote]
|
|
59
|
+
|
|
60
|
+
comparison_with_single_owner_mode:
|
|
61
|
+
protected_branch_detection: full_confirmation_required # single-owner: warning only
|
|
62
|
+
force_push_guardrail: confirmation_text_required # single-owner: warning only
|
|
63
|
+
pre_push_gates: identical # both: lint + test
|
|
64
|
+
pr_automation: enabled # single-owner: disabled
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# Agent Behavior Discipline Standards - AI Optimized
|
|
2
|
+
# Source: core/agent-behavior-discipline.md
|
|
3
|
+
# Inspired by: Karpathy X post 2026-01 + andrej-karpathy-skills CLAUDE.md (MIT)
|
|
4
|
+
|
|
5
|
+
id: agent-behavior-discipline
|
|
6
|
+
meta:
|
|
7
|
+
version: "1.0.0"
|
|
8
|
+
updated: "2026-04-24"
|
|
9
|
+
source: core/agent-behavior-discipline.md
|
|
10
|
+
description: Four behavioral disciplines for AI agents to elevate from functional to excellent — Ask, Simple, Precision, Test
|
|
11
|
+
related:
|
|
12
|
+
- anti-hallucination
|
|
13
|
+
- anti-sycophancy-prompting
|
|
14
|
+
- test-driven-development
|
|
15
|
+
- change-batching-standards
|
|
16
|
+
|
|
17
|
+
principles:
|
|
18
|
+
ask:
|
|
19
|
+
summary: Surface assumptions before executing, not after
|
|
20
|
+
rule: Before any non-trivial task, explicitly state assumptions and wait for confirmation
|
|
21
|
+
triggers:
|
|
22
|
+
- Task has ambiguous requirements or multiple valid interpretations
|
|
23
|
+
- Confidence score < 0.7 (see epistemic-calibration)
|
|
24
|
+
- Task involves architecture changes, refactors, or multi-file modifications
|
|
25
|
+
do:
|
|
26
|
+
- State all assumptions explicitly before starting
|
|
27
|
+
- Present multiple interpretations when the prompt is ambiguous
|
|
28
|
+
- Propose simpler alternatives and challenge requests when appropriate
|
|
29
|
+
- Name confusion explicitly instead of proceeding with a guess
|
|
30
|
+
- Push back when a simpler path exists
|
|
31
|
+
do_not:
|
|
32
|
+
- Assume silently and proceed
|
|
33
|
+
- Use "I understand you want..." phrasing to paper over ambiguity
|
|
34
|
+
- Start executing to demonstrate effort before confirming direction
|
|
35
|
+
disclosure_format: |
|
|
36
|
+
My assumptions: [list]
|
|
37
|
+
Approach considered: [A] vs [B] — choosing A because [reason]
|
|
38
|
+
If my understanding is incorrect, please redirect before I proceed.
|
|
39
|
+
|
|
40
|
+
simple:
|
|
41
|
+
summary: Minimum code that solves the problem, nothing speculative
|
|
42
|
+
rule: Solve with the least code required. Never add unrequested functionality.
|
|
43
|
+
triggers:
|
|
44
|
+
- Any code generation task
|
|
45
|
+
do:
|
|
46
|
+
- Write only what the task requires
|
|
47
|
+
- Rewrite if the solution could be significantly shorter without loss of clarity
|
|
48
|
+
- Inline logic that is only used once (no premature abstraction)
|
|
49
|
+
do_not:
|
|
50
|
+
- Add features "that might be needed later"
|
|
51
|
+
- Create single-use abstractions or helper classes
|
|
52
|
+
- Add speculative flexibility or configuration hooks nobody asked for
|
|
53
|
+
- Add error handling for scenarios that cannot happen
|
|
54
|
+
three_strikes_rule: Abstract only when the same logic appears 3+ times (DRY threshold)
|
|
55
|
+
|
|
56
|
+
precision:
|
|
57
|
+
summary: Touch only what the task requires — clean up only your own mess
|
|
58
|
+
rule: Scope modifications to the minimum set of files and lines required
|
|
59
|
+
triggers:
|
|
60
|
+
- Any edit or refactor task
|
|
61
|
+
do:
|
|
62
|
+
- Declare scope before editing ("I will modify: X. I will not touch: Y.")
|
|
63
|
+
- Match the local code style rather than enforcing personal preferences
|
|
64
|
+
- Flag pre-existing issues found out-of-scope with a verbal note only
|
|
65
|
+
do_not:
|
|
66
|
+
- Improve unrelated code, formatting, or comments while on a scoped task
|
|
67
|
+
- Remove pre-existing dead code outside task scope
|
|
68
|
+
- Rename symbols not involved in the current change
|
|
69
|
+
- Remove imports or variables orphaned by someone else's previous change
|
|
70
|
+
scope_declaration_format: |
|
|
71
|
+
Modifying: [file list]
|
|
72
|
+
Not touching: [related but out-of-scope areas]
|
|
73
|
+
Out-of-scope observation (action deferred): [optional]
|
|
74
|
+
|
|
75
|
+
test:
|
|
76
|
+
summary: Define verifiable success criteria before executing; loop until verified
|
|
77
|
+
rule: Transform every task into a measurable success criterion before implementation
|
|
78
|
+
triggers:
|
|
79
|
+
- Any implementation or bug-fix task
|
|
80
|
+
- Long-running autonomous agent loops
|
|
81
|
+
do:
|
|
82
|
+
- Ask for or define quantifiable success criteria before starting
|
|
83
|
+
- Write a failing test first (TDD red phase), then implement, then refactor
|
|
84
|
+
- State multi-step plans with explicit verification checkpoints
|
|
85
|
+
- Loop autonomously toward the verified goal, recording each iteration's failureSource
|
|
86
|
+
do_not:
|
|
87
|
+
- Accept subjective criteria ("make it better", "improve search quality")
|
|
88
|
+
- Proceed without a stopping condition for autonomous loops
|
|
89
|
+
- Report completion without demonstrating the success criterion was met
|
|
90
|
+
vague_criteria_escalation: |
|
|
91
|
+
If the task uses subjective success language, ask:
|
|
92
|
+
"What specific metric or observable outcome defines success here?"
|
|
93
|
+
loop_protocol:
|
|
94
|
+
max_retries: 5
|
|
95
|
+
on_stuck: escalate to human with failureSource summary
|
|
96
|
+
record: failureSource per iteration (see failure-source-taxonomy)
|
|
97
|
+
|
|
98
|
+
prohibited_behaviors:
|
|
99
|
+
- id: silent-assumption
|
|
100
|
+
description: Do NOT make assumptions about ambiguous requirements without stating them
|
|
101
|
+
correct_action: Use ask.disclosure_format before proceeding
|
|
102
|
+
|
|
103
|
+
- id: speculative-feature
|
|
104
|
+
description: Do NOT implement features that were not explicitly requested
|
|
105
|
+
correct_action: Implement only the requested scope; mention potential extensions verbally
|
|
106
|
+
|
|
107
|
+
- id: scope-creep
|
|
108
|
+
description: Do NOT modify code outside the declared scope of the task
|
|
109
|
+
correct_action: Use precision.scope_declaration_format and flag out-of-scope observations verbally
|
|
110
|
+
|
|
111
|
+
- id: subjective-success
|
|
112
|
+
description: Do NOT accept vague success criteria ("better", "improved", "successful")
|
|
113
|
+
correct_action: Use test.vague_criteria_escalation to obtain a quantifiable criterion
|
|
114
|
+
|
|
115
|
+
- id: open-ended-loop
|
|
116
|
+
description: Do NOT run autonomous correction loops without a defined stopping condition
|
|
117
|
+
correct_action: Define max_retries and escalation path before starting the loop
|
|
118
|
+
|
|
119
|
+
agent_application:
|
|
120
|
+
implementation_tasks:
|
|
121
|
+
apply: [ask, simple, precision, test]
|
|
122
|
+
notes: All four principles apply to every non-trivial implementation task
|
|
123
|
+
refactoring_tasks:
|
|
124
|
+
apply: [ask, precision, test]
|
|
125
|
+
notes: Simplicity is a refactor outcome, not a separate check; Precision is critical
|
|
126
|
+
bug_fix_tasks:
|
|
127
|
+
apply: [ask, precision, test]
|
|
128
|
+
notes: Ask to confirm reproduction steps; Precision to avoid scope creep; Test to define "fixed"
|
|
129
|
+
autonomous_loops:
|
|
130
|
+
apply: [test]
|
|
131
|
+
notes: test.loop_protocol is mandatory for any multi-iteration autonomous agent task
|
|
132
|
+
trivial_tasks:
|
|
133
|
+
apply: []
|
|
134
|
+
threshold: confidence >= 0.9 AND task is single-file AND lines_changed < 5
|
|
135
|
+
notes: Trivial tasks (e.g., adding a comment) may skip ask confirmation
|
|
136
|
+
|
|
137
|
+
checklist:
|
|
138
|
+
- Assumptions stated before execution starts
|
|
139
|
+
- Code solves the problem with minimum required lines
|
|
140
|
+
- Only declared-scope files were modified
|
|
141
|
+
- Success criterion is quantifiable and verified
|
|
142
|
+
- Autonomous loops have max_retries and escalation path defined
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Agent Behavior Discipline
|
|
2
|
+
|
|
3
|
+
> **Language**: English | [繁體中文](../locales/zh-TW/core/agent-behavior-discipline.md)
|
|
4
|
+
|
|
5
|
+
**Version**: 1.0.0
|
|
6
|
+
**Last Updated**: 2026-04-24
|
|
7
|
+
**Applicability**: All AI agent implementations using UDS-compliant harnesses
|
|
8
|
+
**Scope**: universal
|
|
9
|
+
**Industry Standards**: Informed by Karpathy 2026-01 observations + andrej-karpathy-skills (MIT)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Purpose
|
|
14
|
+
|
|
15
|
+
This standard defines four behavioral disciplines for AI agents that elevate performance from "functional" to "excellent". These disciplines address the most common failure modes observed in production LLM coding agents:
|
|
16
|
+
|
|
17
|
+
1. **Executing on wrong assumptions** — agent proceeds without confirming direction
|
|
18
|
+
2. **Over-engineering** — agent writes 200 lines when 50 would suffice
|
|
19
|
+
3. **Scope creep** — agent "helpfully" modifies unrelated code
|
|
20
|
+
4. **Goalless loops** — agent iterates without a defined stopping condition
|
|
21
|
+
|
|
22
|
+
The disciplines are designed to be stackable with existing UDS standards (`anti-hallucination`, `anti-sycophancy-prompting`, `test-driven-development`) and enforceable at the harness level (DevAP `DisciplineConfig`).
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## Principle 1: Ask — Surface Assumptions Before Executing
|
|
27
|
+
|
|
28
|
+
### Rule
|
|
29
|
+
|
|
30
|
+
Before any non-trivial task, explicitly state all assumptions and wait for confirmation.
|
|
31
|
+
|
|
32
|
+
### When to Apply
|
|
33
|
+
|
|
34
|
+
| Condition | Action |
|
|
35
|
+
|-----------|--------|
|
|
36
|
+
| Ambiguous requirements or multiple valid interpretations | Use Disclosure Format (below) |
|
|
37
|
+
| Confidence score < 0.7 | Pause and ask |
|
|
38
|
+
| Architecture changes or multi-file modifications | Always disclose |
|
|
39
|
+
| Single-file trivial change (confidence ≥ 0.9, < 5 lines) | May skip confirmation |
|
|
40
|
+
|
|
41
|
+
### Disclosure Format
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
My assumptions: [explicit list]
|
|
45
|
+
Approach considered: [A] vs [B] — choosing A because [reason]
|
|
46
|
+
If my understanding is incorrect, please redirect before I proceed.
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Why This Matters
|
|
50
|
+
|
|
51
|
+
Karpathy observed: *"Models make wrong assumptions, don't seek clarification, and are a little too sycophantic."* A wrong direction costs more tokens to undo than the upfront 3-second check would have taken.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Principle 2: Simple — Minimum Code, Nothing Speculative
|
|
56
|
+
|
|
57
|
+
### Rule
|
|
58
|
+
|
|
59
|
+
Solve with the least code required. Never add unrequested functionality.
|
|
60
|
+
|
|
61
|
+
### Three Strikes Rule (DRY Threshold)
|
|
62
|
+
|
|
63
|
+
Abstract only when identical logic appears **3 or more times**. A single-use helper is always a premature abstraction.
|
|
64
|
+
|
|
65
|
+
### DO / DO NOT
|
|
66
|
+
|
|
67
|
+
| DO | DO NOT |
|
|
68
|
+
|----|--------|
|
|
69
|
+
| ✅ Write only what the task requires | ❌ Add features "that might be needed later" |
|
|
70
|
+
| ✅ Rewrite when a significantly shorter solution exists | ❌ Create single-use abstractions |
|
|
71
|
+
| ✅ Inline logic used only once | ❌ Add speculative configuration hooks |
|
|
72
|
+
| ✅ Skip error handling for impossible scenarios | ❌ Add defensive code for internal invariants |
|
|
73
|
+
|
|
74
|
+
### Why This Matters
|
|
75
|
+
|
|
76
|
+
Karpathy observed: *"It will implement 1000 lines of bloated code, and when challenged, immediately cuts it to 100."* If it can be 50 lines, it should be 50 lines from the start.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Principle 3: Precision — Touch Only What the Task Requires
|
|
81
|
+
|
|
82
|
+
### Rule
|
|
83
|
+
|
|
84
|
+
Scope modifications to the declared minimum set of files and lines. Clean up only your own mess.
|
|
85
|
+
|
|
86
|
+
### Scope Declaration Format
|
|
87
|
+
|
|
88
|
+
Before any edit, output:
|
|
89
|
+
```
|
|
90
|
+
Modifying: [file list]
|
|
91
|
+
Not touching: [related but out-of-scope areas]
|
|
92
|
+
Out-of-scope observation (action deferred): [optional — verbal only, no edit]
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### DO / DO NOT
|
|
96
|
+
|
|
97
|
+
| DO | DO NOT |
|
|
98
|
+
|----|--------|
|
|
99
|
+
| ✅ Match existing local code style | ❌ Improve unrelated code "while I'm here" |
|
|
100
|
+
| ✅ Flag pre-existing issues verbally | ❌ Remove dead code you didn't create |
|
|
101
|
+
| ✅ Remove only imports orphaned by YOUR change | ❌ Rename symbols not in your task scope |
|
|
102
|
+
| ✅ Declare scope before starting | ❌ Format unrelated code to match your preferences |
|
|
103
|
+
|
|
104
|
+
### Why This Matters
|
|
105
|
+
|
|
106
|
+
Karpathy observed agents that *"alter code it doesn't understand, and then things break"*. Precision prevents untraceable side effects and keeps diffs reviewable.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Principle 4: Test — Define Success Criteria, Loop Until Verified
|
|
111
|
+
|
|
112
|
+
### Rule
|
|
113
|
+
|
|
114
|
+
Transform every task into a measurable, verifiable success criterion before implementation.
|
|
115
|
+
|
|
116
|
+
### TDD Flow
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
Define success criterion → Write failing test (Red) → Implement (Green) → Refactor → Verify
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Vague Criteria Escalation
|
|
123
|
+
|
|
124
|
+
If the task uses subjective language ("make it better", "improve search quality"):
|
|
125
|
+
> "What specific metric or observable outcome defines success here?"
|
|
126
|
+
|
|
127
|
+
Never proceed with a subjective stopping condition.
|
|
128
|
+
|
|
129
|
+
### Autonomous Loop Protocol
|
|
130
|
+
|
|
131
|
+
| Parameter | Value |
|
|
132
|
+
|-----------|-------|
|
|
133
|
+
| max_retries | 5 (default; configurable via DisciplineConfig) |
|
|
134
|
+
| Per-iteration logging | Record `failureSource` (see failure-source-taxonomy) |
|
|
135
|
+
| On stuck (same error fingerprint) | Escalate to human with failureSource summary |
|
|
136
|
+
|
|
137
|
+
### Why This Matters
|
|
138
|
+
|
|
139
|
+
Karpathy's strongest principle: *"LLMs excel at looping toward specific goals — provide success criteria rather than directives."* Without a verifiable goal, an autonomous agent loop has no natural stopping point.
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## Integration with Other UDS Standards
|
|
144
|
+
|
|
145
|
+
| Standard | Relationship |
|
|
146
|
+
|----------|-------------|
|
|
147
|
+
| `anti-hallucination` | Ask principle: disclose when uncertain rather than guessing |
|
|
148
|
+
| `anti-sycophancy-prompting` | Ask principle: don't assume, push back when warranted |
|
|
149
|
+
| `test-driven-development` | Test principle: TDD is the operational implementation |
|
|
150
|
+
| `change-batching-standards` | Precision principle: scope limits reinforce batching logic |
|
|
151
|
+
| `failure-source-taxonomy` | Test principle: loop protocol uses failureSource taxonomy |
|
|
152
|
+
| `recovery-recipe-registry` | Test principle: max_retries maps to recovery recipe escalation |
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Enforcement at Harness Level (DevAP)
|
|
157
|
+
|
|
158
|
+
`DisciplineConfig` in DevAP `src/types.ts`:
|
|
159
|
+
|
|
160
|
+
```typescript
|
|
161
|
+
interface DisciplineConfig {
|
|
162
|
+
ask_threshold: number; // Confidence below this triggers Ask disclosure (default: 0.6)
|
|
163
|
+
max_loop_retries: number; // Autonomous loop ceiling (default: 5)
|
|
164
|
+
precision_scope: 'strict' | 'relaxed'; // strict = always declare scope
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
The `assumptionCheckGate()` in `src/orchestrator.ts` evaluates task complexity against `ask_threshold` before dispatching to the agent.
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Checklist
|
|
173
|
+
|
|
174
|
+
- [ ] Assumptions stated before execution starts
|
|
175
|
+
- [ ] Code solves the problem with minimum required lines
|
|
176
|
+
- [ ] Only declared-scope files were modified
|
|
177
|
+
- [ ] Success criterion is quantifiable and verified
|
|
178
|
+
- [ ] Autonomous loops have `max_retries` and escalation path defined
|
|
@@ -237,7 +237,7 @@ Directories excluded from version control will not be committed, so they should
|
|
|
237
237
|
| Category | Common Directories/Files | Reason |
|
|
238
238
|
|----------|-------------------------|--------|
|
|
239
239
|
| AI Collaboration Tools | `.claude/`, `.cursor/`, `.ai/` | Local development aids, not in version control |
|
|
240
|
-
| Development Standards | `.standards
|
|
240
|
+
| Development Standards | `.standards/` | Local standard docs, not in version control |
|
|
241
241
|
| Build Outputs | `dist/`, `build/`, `out/` | Build artifacts, not in version control |
|
|
242
242
|
| Large Data | `data/`, `datasets/` | Data files, not in version control |
|
|
243
243
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../CHANGELOG.md
|
|
3
|
-
source_version: 5.
|
|
4
|
-
translation_version: 5.
|
|
5
|
-
last_synced: 2026-04-
|
|
3
|
+
source_version: 5.2.0
|
|
4
|
+
translation_version: 5.2.0
|
|
5
|
+
last_synced: 2026-04-24
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -17,6 +17,26 @@ status: current
|
|
|
17
17
|
|
|
18
18
|
## [Unreleased]
|
|
19
19
|
|
|
20
|
+
## [5.2.0] - 2026-04-24
|
|
21
|
+
|
|
22
|
+
> **次版本发布**:三项新标准/技能(XSPEC-080/081/082)—— `/release package` 子命令、`/push` 质量守门 Skill、以及 `agent-behavior-discipline` 标准(Karpathy 四大原则:问/减/准/测)。Bundle 一致性加固。文档集中至 dev-platform。标准总数:74。
|
|
23
|
+
|
|
24
|
+
### 新增
|
|
25
|
+
- **`agent-behavior-discipline.ai.yaml`**(Trial 试验期至 2026-10-24,XSPEC-082 / DEC-048):新治理标准,系统化整合 Andrej Karpathy 提炼的四大 AI Agent 行为纪律——问(执行前揭露假设)、减(最小充分代码)、准(精准修改边界)、测(定义可验证成功标准 + 自我修正循环)。已加入 `uds-manifest.json`(第 74 个标准)及 `cli/standards-registry.json`。
|
|
26
|
+
- **`/push` Skill**(`skills/push/`,XSPEC-081):Git Push 质量守门与跨人协作护栏——受保护分支检测、force-push 护栏、pre-push gate 验证、push 审计日志、PR 集成入口。包含两个配置选项:`options/push/single-owner-mode.ai.yaml`(单人仓库简化护栏)和 `options/push/team-mode.ai.yaml`(团队全护栏,需确认)。
|
|
27
|
+
- **`/release package` 子命令**(`skills/release/`,XSPEC-080):10 种目标格式的打包指引——npm/Node.js、Python/PyPI、Go 二进制、Electron App、Homebrew(Wave 1)+ Rust/Cargo、Tauri 桌面、Docker 镜像、VS Code Extension、GitHub Release 资产(Wave 2)。检测优先设计:自动检测项目类型再套用打包步骤。
|
|
28
|
+
|
|
29
|
+
### 修正
|
|
30
|
+
- **Bundle 一致性**(XSPEC-072 Phase 2):解决 `ai/standards/` 与 `bundle/` 之间的差异——74 个标准现在全部纳入 bundle。CI 硬性失败(exit 1)于任何差异,防止静默的 bundle 落差。
|
|
31
|
+
- **i18n NO META frontmatter**(BUG-A06):补齐 36 个翻译文件缺少的 YAML frontmatter,修复翻译同步验证误报。
|
|
32
|
+
|
|
33
|
+
### 变更
|
|
34
|
+
- **文档集中化(DEC-047 Batch 2)**:UDS 规划/治理文档已迁移至 AsiaOstrich dev-platform 规划中心,不再随 UDS 发布:
|
|
35
|
+
- `docs/AI-AGENT-ROADMAP.md`、`docs/OPERATION-WORKFLOW.md`、`docs/internal/` 下四份文档已移除
|
|
36
|
+
- `locales/zh-TW/docs/`、`locales/zh-CN/docs/` 副本亦已移除
|
|
37
|
+
|
|
38
|
+
[5.2.0]: https://github.com/AsiaOstrich/universal-dev-standards/compare/v5.1.1...v5.2.0
|
|
39
|
+
|
|
20
40
|
## [5.1.1] - 2026-04-20
|
|
21
41
|
|
|
22
42
|
> **补丁版本**:Windows CI 修正、53 个 SKILL.md 补 `name` 字段、三份 `.md` 源文件依 BUG-A08 事后分析新增规则、zh-TW/zh-CN 翻译同步。
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../README.md
|
|
3
|
+
source_version: 5.1.1
|
|
4
|
+
translation_version: 5.1.1
|
|
5
|
+
last_synced: 2026-04-22
|
|
6
|
+
status: current
|
|
7
|
+
---
|
|
8
|
+
|
|
1
9
|
# Universal Development Standards
|
|
2
10
|
|
|
3
11
|
[](https://www.npmjs.com/package/universal-dev-standards)
|
|
@@ -6,7 +14,7 @@
|
|
|
6
14
|
|
|
7
15
|
> **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
|
|
8
16
|
|
|
9
|
-
**版本**: 5.
|
|
17
|
+
**版本**: 5.2.0 | **发布日期**: 2026-04-13 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
|
|
10
18
|
|
|
11
19
|
语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流,确保不同技术栈之间的一致性、质量和可维护性。
|
|
12
20
|
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../../docs/CLI-FLOW.md
|
|
3
|
+
source_version: 1.0.0
|
|
4
|
+
translation_version: 1.0.0
|
|
5
|
+
last_synced: 2026-04-22
|
|
6
|
+
status: current
|
|
7
|
+
---
|
|
8
|
+
|
|
1
9
|
# CLI 命令流程
|
|
2
10
|
|
|
3
11
|
> **Language**: [English](../../../docs/CLI-FLOW.md) | [繁體中文](../../zh-TW/docs/CLI-FLOW.md) | 简体中文
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../../../skills/commands/requirement.md
|
|
3
|
+
source_version: 1.0.0
|
|
4
|
+
translation_version: 1.0.0
|
|
5
|
+
last_synced: 2026-04-22
|
|
6
|
+
status: current
|
|
7
|
+
---
|
|
8
|
+
|
|
1
9
|
---
|
|
2
10
|
description: [UDS] Write user stories and requirements following INVEST criteria
|
|
3
11
|
allowed-tools: Read, Write, Grep, Glob
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../../../skills/commands/reverse-bdd.md
|
|
3
|
+
source_version: 1.0.0
|
|
4
|
+
translation_version: 1.0.0
|
|
5
|
+
last_synced: 2026-04-22
|
|
6
|
+
status: current
|
|
7
|
+
---
|
|
8
|
+
|
|
1
9
|
---
|
|
2
10
|
description: [UDS] Transform SDD acceptance criteria to BDD scenarios
|
|
3
11
|
allowed-tools: Read, Grep, Glob, Write
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../../../skills/commands/reverse-sdd.md
|
|
3
|
+
source_version: 1.0.0
|
|
4
|
+
translation_version: 1.0.0
|
|
5
|
+
last_synced: 2026-04-22
|
|
6
|
+
status: current
|
|
7
|
+
---
|
|
8
|
+
|
|
1
9
|
---
|
|
2
10
|
description: [UDS] Reverse engineer code into SDD specification document
|
|
3
11
|
allowed-tools: Read, Grep, Glob, Write
|
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../../../skills/commands/reverse-tdd.md
|
|
3
|
+
source_version: 1.0.0
|
|
4
|
+
translation_version: 1.0.0
|
|
5
|
+
last_synced: 2026-04-22
|
|
6
|
+
status: current
|
|
7
|
+
---
|
|
8
|
+
|
|
1
9
|
---
|
|
2
10
|
description: [UDS] Analyze BDD-TDD coverage gaps
|
|
3
11
|
allowed-tools: Read, Grep, Glob, Write
|