contextos-agents 2.1.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/.agents/AGENTS.md +53 -396
  2. package/.agents/adapters/aider/export.js +11 -16
  3. package/.agents/adapters/claude/export.js +13 -13
  4. package/.agents/adapters/copilot/export.js +29 -8
  5. package/.agents/adapters/cursor/export.js +9 -18
  6. package/.agents/adapters/gemini/export.js +11 -46
  7. package/.agents/adapters/pure-compiler.js +65 -42
  8. package/.agents/adapters/shared.js +35 -1
  9. package/.agents/adapters/zed/export.js +2 -2
  10. package/.agents/compiled/registry.v2.json +30 -18
  11. package/.agents/compiled/registry.v2.sha256 +1 -1
  12. package/.agents/compiler/manifest-compiler.js +5 -29
  13. package/.agents/core/skills/context-os/references/project-graph.md +3 -3
  14. package/.agents/core/skills/engineering-workflow/SKILL.md +11 -316
  15. package/.agents/core/skills/engineering-workflow/references/workflow.md +336 -0
  16. package/.agents/core/skills/engineering-workflow/skill.yaml +2 -4
  17. package/.agents/core/skills/gstack-roles/SKILL.md +11 -128
  18. package/.agents/core/skills/gstack-roles/references/roles.md +149 -0
  19. package/.agents/core/skills/gstack-roles/skill.yaml +2 -4
  20. package/.agents/core/skills/ponytail-mindset/SKILL.md +13 -165
  21. package/.agents/core/skills/ponytail-mindset/references/minimalism.md +186 -0
  22. package/.agents/core/skills/ponytail-mindset/skill.yaml +2 -5
  23. package/.agents/core/skills/security/skill.yaml +1 -0
  24. package/.agents/ctx.js +22 -17
  25. package/.agents/customization-dx.js +13 -9
  26. package/.agents/doctor.js +2 -2
  27. package/.agents/generated/claude/skills/context-manager/EXAMPLES.md +19 -0
  28. package/.agents/generated/claude/skills/context-manager/SKILL.md +0 -29
  29. package/.agents/generated/claude/skills/context-manager/TROUBLESHOOTING.md +7 -0
  30. package/.agents/generated/claude/skills/context-manager/VALIDATION.json +12 -0
  31. package/.agents/generated/claude/skills/context-manager/references/context-rules.md +59 -0
  32. package/.agents/generated/claude/skills/context-os/EXAMPLES.md +21 -0
  33. package/.agents/generated/claude/skills/context-os/SKILL.md +0 -31
  34. package/.agents/generated/claude/skills/context-os/TROUBLESHOOTING.md +7 -0
  35. package/.agents/generated/claude/skills/context-os/VALIDATION.json +12 -0
  36. package/.agents/generated/claude/skills/context-os/packs.yaml +59 -0
  37. package/.agents/generated/claude/skills/context-os/references/context-rules.md +68 -0
  38. package/.agents/generated/claude/skills/context-os/references/pipeline.md +119 -0
  39. package/.agents/generated/claude/skills/context-os/references/project-graph.md +103 -0
  40. package/.agents/generated/claude/skills/context-os/rules.yaml +135 -0
  41. package/.agents/generated/claude/skills/engineering-workflow/EXAMPLES.md +57 -0
  42. package/.agents/generated/claude/skills/engineering-workflow/SKILL.md +10 -391
  43. package/.agents/generated/claude/skills/engineering-workflow/TROUBLESHOOTING.md +19 -0
  44. package/.agents/generated/claude/skills/engineering-workflow/VALIDATION.json +12 -0
  45. package/.agents/generated/claude/skills/engineering-workflow/references/workflow.md +336 -0
  46. package/.agents/generated/claude/skills/gemini-precision/EXAMPLES.md +72 -0
  47. package/.agents/generated/claude/skills/gemini-precision/SKILL.md +0 -100
  48. package/.agents/generated/claude/skills/gemini-precision/TROUBLESHOOTING.md +25 -0
  49. package/.agents/generated/claude/skills/gemini-precision/VALIDATION.json +12 -0
  50. package/.agents/generated/claude/skills/gstack-roles/EXAMPLES.md +23 -0
  51. package/.agents/generated/claude/skills/gstack-roles/SKILL.md +10 -164
  52. package/.agents/generated/claude/skills/gstack-roles/TROUBLESHOOTING.md +13 -0
  53. package/.agents/generated/claude/skills/gstack-roles/VALIDATION.json +12 -0
  54. package/.agents/generated/claude/skills/gstack-roles/references/roles.md +149 -0
  55. package/.agents/generated/claude/skills/ponytail-mindset/EXAMPLES.md +45 -0
  56. package/.agents/generated/claude/skills/ponytail-mindset/SKILL.md +12 -228
  57. package/.agents/generated/claude/skills/ponytail-mindset/TROUBLESHOOTING.md +19 -0
  58. package/.agents/generated/claude/skills/ponytail-mindset/VALIDATION.json +12 -0
  59. package/.agents/generated/claude/skills/ponytail-mindset/references/minimalism.md +186 -0
  60. package/.agents/generated/claude/skills/security/EXAMPLES.md +64 -0
  61. package/.agents/generated/claude/skills/security/SKILL.md +0 -86
  62. package/.agents/generated/claude/skills/security/TROUBLESHOOTING.md +19 -0
  63. package/.agents/generated/claude/skills/security/VALIDATION.json +12 -0
  64. package/.agents/generated/gemini/skills/context-manager/EXAMPLES.md +19 -0
  65. package/.agents/generated/gemini/skills/context-manager/SKILL.md +1 -33
  66. package/.agents/generated/gemini/skills/context-manager/TROUBLESHOOTING.md +7 -0
  67. package/.agents/generated/gemini/skills/context-manager/VALIDATION.json +12 -0
  68. package/.agents/generated/gemini/skills/context-manager/references/context-rules.md +59 -0
  69. package/.agents/generated/gemini/skills/context-os/EXAMPLES.md +21 -0
  70. package/.agents/generated/gemini/skills/context-os/SKILL.md +0 -35
  71. package/.agents/generated/gemini/skills/context-os/TROUBLESHOOTING.md +7 -0
  72. package/.agents/generated/gemini/skills/context-os/VALIDATION.json +12 -0
  73. package/.agents/generated/gemini/skills/context-os/packs.yaml +59 -0
  74. package/.agents/generated/gemini/skills/context-os/references/context-rules.md +68 -0
  75. package/.agents/generated/gemini/skills/context-os/references/pipeline.md +119 -0
  76. package/.agents/generated/gemini/skills/context-os/references/project-graph.md +103 -0
  77. package/.agents/generated/gemini/skills/context-os/rules.yaml +135 -0
  78. package/.agents/generated/gemini/skills/engineering-workflow/EXAMPLES.md +57 -0
  79. package/.agents/generated/gemini/skills/engineering-workflow/SKILL.md +11 -396
  80. package/.agents/generated/gemini/skills/engineering-workflow/TROUBLESHOOTING.md +19 -0
  81. package/.agents/generated/gemini/skills/engineering-workflow/VALIDATION.json +12 -0
  82. package/.agents/generated/gemini/skills/engineering-workflow/references/workflow.md +336 -0
  83. package/.agents/generated/gemini/skills/gemini-precision/EXAMPLES.md +72 -0
  84. package/.agents/generated/gemini/skills/gemini-precision/SKILL.md +0 -104
  85. package/.agents/generated/gemini/skills/gemini-precision/TROUBLESHOOTING.md +25 -0
  86. package/.agents/generated/gemini/skills/gemini-precision/VALIDATION.json +12 -0
  87. package/.agents/generated/gemini/skills/gstack-roles/EXAMPLES.md +23 -0
  88. package/.agents/generated/gemini/skills/gstack-roles/SKILL.md +11 -169
  89. package/.agents/generated/gemini/skills/gstack-roles/TROUBLESHOOTING.md +13 -0
  90. package/.agents/generated/gemini/skills/gstack-roles/VALIDATION.json +12 -0
  91. package/.agents/generated/gemini/skills/gstack-roles/references/roles.md +149 -0
  92. package/.agents/generated/gemini/skills/ponytail-mindset/EXAMPLES.md +45 -0
  93. package/.agents/generated/gemini/skills/ponytail-mindset/SKILL.md +13 -233
  94. package/.agents/generated/gemini/skills/ponytail-mindset/TROUBLESHOOTING.md +19 -0
  95. package/.agents/generated/gemini/skills/ponytail-mindset/VALIDATION.json +12 -0
  96. package/.agents/generated/gemini/skills/ponytail-mindset/references/minimalism.md +186 -0
  97. package/.agents/generated/gemini/skills/security/EXAMPLES.md +64 -0
  98. package/.agents/generated/gemini/skills/security/SKILL.md +2 -92
  99. package/.agents/generated/gemini/skills/security/TROUBLESHOOTING.md +19 -0
  100. package/.agents/generated/gemini/skills/security/VALIDATION.json +12 -0
  101. package/.agents/plugins.js +272 -28
  102. package/.agents/resolver/canonical-resolver.js +43 -7
  103. package/.agents/resolver/resolve-args.js +31 -0
  104. package/.agents/stats.js +8 -11
  105. package/.agents/workspace/workspace-graph.js +16 -6
  106. package/README.md +61 -6
  107. package/bin/index.js +157 -51
  108. package/bin/lib/ui.js +140 -0
  109. package/package.json +5 -2
@@ -1,193 +1,41 @@
1
1
  ---
2
2
  name: ponytail-mindset
3
- description: >
4
- Minimalist coding mindset. Write only what is strictly necessary for the task.
5
- 7-rung decision ladder before writing any code. Eliminates premature abstraction
6
- while keeping all safety, validation, error handling, and security guards intact.
3
+ description: Choose a minimal maintainable implementation for substantive Build tasks while preserving safety and verification.
7
4
  ---
8
5
 
9
6
  # ponytail-mindset
10
7
 
11
8
  ## Overview
12
9
 
13
- Minimalist engineering discipline that eliminates over-engineering and premature abstraction while maintaining 100% of required validation, type safety, error boundaries, and security invariants.
10
+ Reduce unnecessary code and dependencies without weakening correctness or security.
14
11
 
15
12
  ## When to Use
16
13
 
17
- Activate on all BUILD phases to prevent bloated implementations and enforce concise, focused solutions.
14
+ Substantive implementation and refactoring during Build.
18
15
 
19
16
  ## Rules & Patterns
20
17
 
21
- Based on [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
18
+ Before adding code, check whether the feature is needed and whether existing code, the standard library, the platform, or an installed dependency handles it. Then implement the smallest readable solution. Avoid premature abstractions. Preserve validation, authorization, parameterized queries, meaningful error handling, and required tests.
22
19
 
23
- > _He says nothing. He writes one line. It works._
20
+ The 7-rung ladder: YAGNI; reuse project code; standard library; native platform;
21
+ installed dependencies; a readable one-liner; the minimum maintainable code.
24
22
 
25
- **Core Impact**: Dramatically reduces code footprint by eliminating premature abstraction, YAGNI violations, and boilerplate, while keeping all safety invariants (validation, error handling, security) 100% intact.
26
-
27
- ---
28
-
29
- ### Core Principle
30
-
31
- > **The best code is code you don't write.**
32
- > Write only what the task strictly needs. Lazy about the solution, never about reading and understanding.
33
-
34
- ---
35
-
36
- ### The 7-Rung Decision Ladder
37
-
38
- **Before writing ANY code**, stop and check each rung in order. Stop at the first rung that holds:
39
-
40
- ```text
41
- 1. Does this need to exist?
42
- → No: YAGNI — skip it entirely. Don't build for "future use."
43
-
44
- 2. Already in this codebase or component library?
45
- → Yes: Reuse it. Don't rewrite. Call the existing function/component/module.
46
- → For UI: Check shadcn/ui FIRST. Before building a complex UI element from scratch, check if it exists in the component library. If yes, generate the install command: npx shadcn@latest add dialog — never manually rewrite what shadcn already provides.
47
-
48
- 3. Standard library does it?
49
- → Yes: Use it. Don't write formatDate() — use Intl.DateTimeFormat or dayjs.
50
-
51
- 4. Native platform feature?
52
- → Yes: Use it. Don't install flatpickr when <input type="date"> exists.
53
- → Exception for UI Components: If a native HTML element (like <input type="date"> or <select>) CANNOT be styled consistently across Chrome, Safari, and Firefox to match the premium design system — use the established component library (e.g., shadcn/ui <DatePicker>, <Select>) instead. Cross-browser inconsistency is a legitimate reason to NOT use native.
54
-
55
- 5. Already-installed dependency?
56
- → Yes: Use it. Don't install a new library to do what an existing one can.
57
-
58
- 6. Can it be done in one line?
59
- → Yes: One line. No abstraction layer needed.
60
-
61
- 7. Only then: write the MINIMUM that works.
62
- → No classes when a function works. No module when an inline does.
63
- ```
64
-
65
- ---
66
-
67
- ### The Rule of Three (Do Not Abstract Early)
68
-
69
- - **First occurrence**: Write it inline directly where it is needed.
70
- - **Second occurrence**: Duplicate it cleanly. Duplication is cheaper than the wrong abstraction.
71
- - **Third occurrence**: Only now extract a shared helper or utility.
72
-
73
- ---
74
-
75
- ### 10 Concrete Over-Engineering Red Flags
76
-
77
- 1. Creating a `GenericRepository<T>` when you only have 2 database tables.
78
- 2. Creating a custom state machine or complex reducer for 2 boolean flags.
79
- 3. Adding a configuration file or environment variables for values that never change.
80
- 4. Writing custom retry/circuit-breaker logic when native `fetch` or SDK already handles it.
81
- 5. Building a generic `BaseService` with 15 hook methods implemented by only one class.
82
- 6. Wrapping every standard library call in a custom helper class (`StringUtils`, `DateUtils`, `ObjectUtils`).
83
- 7. Creating a multi-level folder structure (`domains/auth/adapters/driving/rest/controllers/dto/`) for a 30-line microservice.
84
- 8. Writing custom mock frameworks when Vitest/Jest/Node test runner provide standard mocks.
85
- 9. Installing a 50KB npm package for a 3-line utility (e.g. `left-pad`, `is-number`, `deep-clone`).
86
- 10. Pre-optimizing caching and indexing for endpoints serving 10 requests a day.
87
-
88
- ---
89
-
90
- ### The Sacred Exceptions (NEVER Cut These)
91
-
92
- The ladder applies to features and abstractions. These 4 areas are **non-negotiable** and **never simplified away**:
93
-
94
- #### 1. Input Validation
95
-
96
- ```javascript
97
- // [GOOD] Always validate — even if "internal" API
98
- function createUser(data) {
99
- if (!data.email || !isValidEmail(data.email)) {
100
- throw new ValidationError('Invalid email');
101
- }
102
- return db.insert('users', data);
103
- }
104
-
105
- // [BAD] Never skip validation for "speed"
106
- function createUser(data) {
107
- return db.insert('users', data); // NEVER
108
- }
109
- ```
110
-
111
- #### 2. Error Handling
112
-
113
- ```javascript
114
- // [GOOD] Always handle errors explicitly
115
- async function fetchUser(id) {
116
- try {
117
- const user = await db.findById(id);
118
- if (!user) throw new NotFoundError(`User ${id} not found`);
119
- return user;
120
- } catch (err) {
121
- logger.error('fetchUser failed', { id, err });
122
- throw err;
123
- }
124
- }
125
- ```
126
-
127
- #### 3. Security Checks
128
-
129
- - Authorization check BEFORE every query or mutation.
130
- - Parameterized queries everywhere — zero string concatenation in SQL.
131
- - Strict sanitization of all rendered HTML and markdown.
132
-
133
- #### 4. Type Safety & Behavioral Tests
134
-
135
- - Strict TypeScript types — no `any` evasion.
136
- - Tests covering happy path, 4xx, and 5xx edge cases.
137
-
138
- ---
23
+ Read [references/minimalism.md](references/minimalism.md) for detailed procedures and examples only when needed.
139
24
 
140
25
  ## Code Examples
141
26
 
142
- ### Native Platform vs Over-Built Package
143
-
144
- **Over-build**:
145
-
146
- ```bash
147
- npm install flatpickr
148
- # Creates DatePickerWrapper.jsx (45 lines) + useDatePicker.js (30 lines) + styles (60 lines)
149
- ```
150
-
151
- **Ponytail approach (rung 4)**:
152
-
153
- ```html
154
- <input type="date" name="date" aria-label="Appointment date" />
155
- ```
156
-
157
- ### Next.js App Router Server Action vs REST Endpoint
158
-
159
- ```typescript
160
- // Instead of /api/users/[id]/route.ts + custom fetch wrapper:
161
- "use server";
162
-
163
- export async function updateUser(id: string, data: UpdateUserInput) {
164
- const session = await getSession(); // auth check — never skip
165
- if (session?.userId !== id) throw new Error("Forbidden");
166
- return db.users.update(id, data);
167
- }
168
- ```
169
-
170
- ---
27
+ Reuse the existing date formatter. A shorter database query still needs authorization and validated input.
171
28
 
172
29
  ## Validation Checklist
173
30
 
174
- - [ ] Every new dependency has been verified: cannot be solved with native platform or existing dependencies.
175
- - [ ] No single-use abstractions, wrappers, or interfaces created.
176
- - [ ] Sacred exceptions preserved: 100% input validation, explicit error handling, security checks intact.
177
- - [ ] All code written passes all existing unit and integration tests.
178
-
179
- ---
31
+ - [ ] The requested outcome is handled.
32
+ - [ ] Relevant verification and safety boundaries are preserved.
33
+ - [ ] Limitations are stated.
180
34
 
181
35
  ## Common Mistakes
182
36
 
183
- - **Cutting validation to write less code**: The goal is less architecture/boilerplate, never less safety.
184
- - **Creating utilities "for future use"**: Only write utilities when used 3+ times.
185
- - **Rewriting component libraries**: Building custom modals, tabs, or tooltips from scratch when shadcn/ui or Radix is already in the project.
186
-
187
- ---
37
+ Repeated approval after authorization; unnecessary ceremonies for routine edits; treating role labels or string checks as behavioral proof.
188
38
 
189
39
  ## Integration Notes
190
40
 
191
- - Runs at the start of every `[PHASE: Build]` and `[PHASE: Review]`.
192
- - Enforces minimalism alongside `system-design` (think at scale, implement minimally).
193
- - Pairs with `impeccable-design` for UI tasks.
41
+ Load relevant domain skills and supporting resources on demand. Compatibility identifiers remain available.
@@ -0,0 +1,186 @@
1
+
2
+ # ponytail-mindset
3
+
4
+ ## Overview
5
+
6
+ Minimalist engineering discipline that eliminates over-engineering and premature abstraction while maintaining 100% of required validation, type safety, error boundaries, and security invariants.
7
+
8
+ ## When to Use
9
+
10
+ Activate on all BUILD phases to prevent bloated implementations and enforce concise, focused solutions.
11
+
12
+ ## Rules & Patterns
13
+
14
+ Based on [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
15
+
16
+ > _He says nothing. He writes one line. It works._
17
+
18
+ **Core Impact**: Dramatically reduces code footprint by eliminating premature abstraction, YAGNI violations, and boilerplate, while keeping all safety invariants (validation, error handling, security) 100% intact.
19
+
20
+ ---
21
+
22
+ ### Core Principle
23
+
24
+ > **The best code is code you don't write.**\
25
+ > Write only what the task strictly needs. Lazy about the solution, never about reading and understanding.
26
+
27
+ ---
28
+
29
+ ### The 7-Rung Decision Ladder
30
+
31
+ **Before writing ANY code**, stop and check each rung in order. Stop at the first rung that holds:
32
+
33
+ ```text
34
+ 1. Does this need to exist?
35
+ → No: YAGNI — skip it entirely. Don't build for "future use."
36
+
37
+ 2. Already in this codebase or component library?
38
+ → Yes: Reuse it. Don't rewrite. Call the existing function/component/module.
39
+ → For UI: Check shadcn/ui FIRST. Before building a complex UI element from scratch, check if it exists in the component library. If yes, generate the install command: npx shadcn@latest add dialog — never manually rewrite what shadcn already provides.
40
+
41
+ 3. Standard library does it?
42
+ → Yes: Use it. Don't write formatDate() — use Intl.DateTimeFormat or dayjs.
43
+
44
+ 4. Native platform feature?
45
+ → Yes: Use it. Don't install flatpickr when <input type="date"> exists.
46
+ → Exception for UI Components: If a native HTML element (like <input type="date"> or <select>) CANNOT be styled consistently across Chrome, Safari, and Firefox to match the premium design system — use the established component library (e.g., shadcn/ui <DatePicker>, <Select>) instead. Cross-browser inconsistency is a legitimate reason to NOT use native.
47
+
48
+ 5. Already-installed dependency?
49
+ → Yes: Use it. Don't install a new library to do what an existing one can.
50
+
51
+ 6. Can it be done in one line?
52
+ → Yes: One line. No abstraction layer needed.
53
+
54
+ 7. Only then: write the MINIMUM that works.
55
+ → No classes when a function works. No module when an inline does.
56
+ ```
57
+
58
+ ---
59
+
60
+ ### The Rule of Three (Do Not Abstract Early)
61
+
62
+ - **First occurrence**: Write it inline directly where it is needed.
63
+ - **Second occurrence**: Duplicate it cleanly. Duplication is cheaper than the wrong abstraction.
64
+ - **Third occurrence**: Only now extract a shared helper or utility.
65
+
66
+ ---
67
+
68
+ ### 10 Concrete Over-Engineering Red Flags
69
+
70
+ 1. Creating a `GenericRepository<T>` when you only have 2 database tables.
71
+ 2. Creating a custom state machine or complex reducer for 2 boolean flags.
72
+ 3. Adding a configuration file or environment variables for values that never change.
73
+ 4. Writing custom retry/circuit-breaker logic when native `fetch` or SDK already handles it.
74
+ 5. Building a generic `BaseService` with 15 hook methods implemented by only one class.
75
+ 6. Wrapping every standard library call in a custom helper class (`StringUtils`, `DateUtils`, `ObjectUtils`).
76
+ 7. Creating a multi-level folder structure (`domains/auth/adapters/driving/rest/controllers/dto/`) for a 30-line microservice.
77
+ 8. Writing custom mock frameworks when Vitest/Jest/Node test runner provide standard mocks.
78
+ 9. Installing a 50KB npm package for a 3-line utility (e.g. `left-pad`, `is-number`, `deep-clone`).
79
+ 10. Pre-optimizing caching and indexing for endpoints serving 10 requests a day.
80
+
81
+ ---
82
+
83
+ ### The Sacred Exceptions (NEVER Cut These)
84
+
85
+ The ladder applies to features and abstractions. These 4 areas are **non-negotiable** and **never simplified away**:
86
+
87
+ #### 1. Input Validation
88
+
89
+ ```javascript
90
+ // [GOOD] Always validate — even if "internal" API
91
+ function createUser(data) {
92
+ if (!data.email || !isValidEmail(data.email)) {
93
+ throw new ValidationError('Invalid email');
94
+ }
95
+ return db.insert('users', data);
96
+ }
97
+
98
+ // [BAD] Never skip validation for "speed"
99
+ function createUser(data) {
100
+ return db.insert('users', data); // NEVER
101
+ }
102
+ ```
103
+
104
+ #### 2. Error Handling
105
+
106
+ ```javascript
107
+ // [GOOD] Always handle errors explicitly
108
+ async function fetchUser(id) {
109
+ try {
110
+ const user = await db.findById(id);
111
+ if (!user) throw new NotFoundError(`User ${id} not found`);
112
+ return user;
113
+ } catch (err) {
114
+ logger.error('fetchUser failed', { id, err });
115
+ throw err;
116
+ }
117
+ }
118
+ ```
119
+
120
+ #### 3. Security Checks
121
+
122
+ - Authorization check BEFORE every query or mutation.
123
+ - Parameterized queries everywhere — zero string concatenation in SQL.
124
+ - Strict sanitization of all rendered HTML and markdown.
125
+
126
+ #### 4. Type Safety & Behavioral Tests
127
+
128
+ - Strict TypeScript types — no `any` evasion.
129
+ - Tests covering happy path, 4xx, and 5xx edge cases.
130
+
131
+ ---
132
+
133
+ ## Code Examples
134
+
135
+ ### Native Platform vs Over-Built Package
136
+
137
+ **Over-build**:
138
+
139
+ ```bash
140
+ npm install flatpickr
141
+ # Creates DatePickerWrapper.jsx (45 lines) + useDatePicker.js (30 lines) + styles (60 lines)
142
+ ```
143
+
144
+ **Ponytail approach (rung 4)**:
145
+
146
+ ```html
147
+ <input type="date" name="date" aria-label="Appointment date" />
148
+ ```
149
+
150
+ ### Next.js App Router Server Action vs REST Endpoint
151
+
152
+ ```typescript
153
+ // Instead of /api/users/[id]/route.ts + custom fetch wrapper:
154
+ "use server";
155
+
156
+ export async function updateUser(id: string, data: UpdateUserInput) {
157
+ const session = await getSession(); // auth check — never skip
158
+ if (session?.userId !== id) throw new Error("Forbidden");
159
+ return db.users.update(id, data);
160
+ }
161
+ ```
162
+
163
+ ---
164
+
165
+ ## Validation Checklist
166
+
167
+ - [ ] Every new dependency has been verified: cannot be solved with native platform or existing dependencies.
168
+ - [ ] No single-use abstractions, wrappers, or interfaces created.
169
+ - [ ] Sacred exceptions preserved: 100% input validation, explicit error handling, security checks intact.
170
+ - [ ] All code written passes all existing unit and integration tests.
171
+
172
+ ---
173
+
174
+ ## Common Mistakes
175
+
176
+ - **Cutting validation to write less code**: The goal is less architecture/boilerplate, never less safety.
177
+ - **Creating utilities "for future use"**: Only write utilities when used 3+ times.
178
+ - **Rewriting component libraries**: Building custom modals, tabs, or tooltips from scratch when shadcn/ui or Radix is already in the project.
179
+
180
+ ---
181
+
182
+ ## Integration Notes
183
+
184
+ - Applies during substantive Build work and reviews of implementation complexity.
185
+ - Enforces minimalism alongside `system-design` (think at scale, implement minimally).
186
+ - Pairs with `impeccable-design` for UI tasks.
@@ -1,14 +1,11 @@
1
1
  schemaVersion: 2
2
2
  name: ponytail-mindset
3
3
  type: instruction-only
4
- description: >
5
- Minimalist coding mindset based on DietrichGebert/ponytail.
6
- Teaches the AI to write only what is strictly necessary.
7
- Uses a 7-rung ladder: YAGNI → reuse → stdlib → platform → deps → one-liner → minimum.
8
- Minimizes unnecessary boilerplate and over-engineering while keeping all safety, validation and security guards.
4
+ description: Choose a minimal maintainable implementation for substantive Build tasks while preserving safety and verification.
9
5
  version: 1.0.0
10
6
  resources:
11
7
  - EXAMPLES.md
12
8
  - SKILL.md
13
9
  - TROUBLESHOOTING.md
14
10
  - VALIDATION.json
11
+ - references/minimalism.md
@@ -1,6 +1,7 @@
1
1
  schemaVersion: 2
2
2
  id: security
3
3
  name: Application Security
4
+ description: Protect authentication, authorization, sensitive data, untrusted input, external integrations, and agent tool execution.
4
5
  category: backend
5
6
  type: instruction-only
6
7
  requires: []
package/.agents/ctx.js CHANGED
@@ -55,10 +55,13 @@ function printHelp() {
55
55
  console.log(' watch Start continuous file watcher and auto-sync daemon');
56
56
  console.log(' init Show initialization guide');
57
57
  console.log(' install-skill <ref> Alias for skill add (install a plugin)');
58
- console.log(' skill add <ref> Install a plugin skill (GitHub or npm)');
58
+ console.log(' skill add <ref|--all> Install a plugin skill or all catalog skills (--all)');
59
59
  console.log(' skill remove <name> Uninstall a plugin skill');
60
- console.log(' skill list List installed skills (builtin + plugins)');
60
+ console.log(' skill list [--available] List installed skills (and available catalog skills)');
61
61
  console.log(' skill search [query] Search the community skill registry');
62
+ console.log(' skill override <name> Create editable project copy of an upstream skill');
63
+ console.log(' skill diff <name> Show differences between local override and upstream');
64
+ console.log(' skill eject <name> Eject upstream skill to standalone project skill');
62
65
  console.log('');
63
66
  console.log('Plugin ref formats:');
64
67
  console.log(' username/repo GitHub repo root SKILL.md');
@@ -367,22 +370,22 @@ if (command === 'export') {
367
370
  // ── resolve ───────────────────────────────────────────────────────────────────
368
371
  } else if (command === 'resolve') {
369
372
  const { CanonicalResolver } = require('./resolver/canonical-resolver.js');
370
- const promptArgs = args.slice(1).filter(a => !a.startsWith('-')).join(' ');
371
- const filesIdx = args.indexOf('--files');
372
- const files = filesIdx !== -1 && args[filesIdx + 1] ? args[filesIdx + 1].split(',') : [];
373
- const phaseIdx = args.indexOf('--phase');
374
- const phase = phaseIdx !== -1 && args[phaseIdx + 1] ? args[phaseIdx + 1] : undefined;
375
- const budgetIdx = args.indexOf('--budget');
376
- const budget = budgetIdx !== -1 && args[budgetIdx + 1] ? parseInt(args[budgetIdx + 1], 10) : undefined;
377
- const explain = args.includes('--explain');
378
- const asJson = args.includes('--json');
373
+ const { parseResolveArgs } = require('./resolver/resolve-args.js');
374
+ let parsed;
375
+ try {
376
+ parsed = parseResolveArgs(args.slice(1));
377
+ } catch (error) {
378
+ console.error(error.message);
379
+ process.exit(1);
380
+ }
381
+ const { json: asJson, explain } = parsed;
379
382
 
380
383
  const resolver = new CanonicalResolver({ rootDir: process.cwd() });
381
384
  const result = resolver.resolve({
382
- task: promptArgs,
383
- files,
384
- explicitPhase: phase,
385
- contextBudgetTokens: budget,
385
+ task: parsed.task,
386
+ files: parsed.files,
387
+ explicitPhase: parsed.explicitPhase,
388
+ contextBudgetTokens: parsed.contextBudgetTokens,
386
389
  });
387
390
 
388
391
  if (asJson) {
@@ -634,15 +637,17 @@ if (command === 'export') {
634
637
  }
635
638
 
636
639
  if (subcommand === 'add') {
640
+ const isAll = args.includes('--all') || ref === '--all' || ref === 'all';
637
641
  const forceUnsafe = args.includes('--force-unsafe-prompts') || args.includes('--force-unsafe');
638
- plugins.add(ref, { dryRun, checksum, forceUnsafe }).catch(err => {
642
+ plugins.add(isAll ? '--all' : ref, { dryRun, checksum, forceUnsafe, all: isAll }).catch(err => {
639
643
  console.error(`[ERROR] ${err.message}`);
640
644
  process.exit(1);
641
645
  });
642
646
  } else if (subcommand === 'remove') {
643
647
  plugins.remove(ref);
644
648
  } else if (subcommand === 'list') {
645
- plugins.list();
649
+ const available = args.includes('--available') || args.includes('-a') || args.includes('--all');
650
+ plugins.list({ available });
646
651
  } else if (subcommand === 'search') {
647
652
  const query = args.slice(2).join(' ');
648
653
  plugins.search(query).catch(err => {
@@ -29,6 +29,7 @@ class SkillCustomizationManager {
29
29
  }
30
30
 
31
31
  _findUpstreamSkill(skillName) {
32
+ if (!/^[a-z0-9-]+$/.test(skillName)) throw new Error('Invalid skill ID');
32
33
  const inCore = path.join(this.coreSkillsDir, skillName);
33
34
  if (fs.existsSync(inCore)) return inCore;
34
35
 
@@ -59,16 +60,19 @@ class SkillCustomizationManager {
59
60
  throw err;
60
61
  }
61
62
 
62
- fs.mkdirSync(targetDir, { recursive: true });
63
-
64
- // Copy SKILL.md and skill.yaml if present
65
- const files = fs.readdirSync(upstream);
66
- for (const file of files) {
67
- const srcFile = path.join(upstream, file);
68
- if (fs.statSync(srcFile).isFile()) {
69
- fs.copyFileSync(srcFile, path.join(targetDir, file));
63
+ // Validate the complete source tree before creating an override.
64
+ const { resolveManagedPath } = require('./filesystem/index.js');
65
+ const inspect = (dir) => {
66
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
67
+ const source = path.join(dir, entry.name);
68
+ if (entry.isSymbolicLink()) throw new Error(`Skill override refuses symlink: ${source}`);
69
+ resolveManagedPath(upstream, path.relative(upstream, source));
70
+ if (entry.isDirectory()) inspect(source);
70
71
  }
71
- }
72
+ };
73
+ inspect(upstream);
74
+ resolveManagedPath(this.projectRoot, path.relative(this.projectRoot, targetDir));
75
+ fs.cpSync(upstream, targetDir, { recursive: true, errorOnExist: true, force: false });
72
76
 
73
77
  return {
74
78
  success: true,
package/.agents/doctor.js CHANGED
@@ -238,8 +238,8 @@ function checkSecretScanner(projectDir) {
238
238
  id: 'secret_scanner',
239
239
  status: STATUS.FAIL,
240
240
  ok: false,
241
- message: 'potential secrets detected in workspace',
242
- remediation: 'Run `npm run check:secrets` and resolve flagged secrets or add to allowlist',
241
+ message: err.status === 1 ? 'potential secrets detected in workspace' : `Secret scanner unavailable (exit ${err.status ?? err.code ?? 'unknown'}): ${(err.stderr || err.message || '').toString().split(/\r?\n/).find(Boolean) || 'execution failed'}`,
242
+ remediation: err.status === 1 ? 'Run `npm run check:secrets` and resolve flagged secrets or add to allowlist' : 'Run `npm run check:secrets` and resolve the scanner execution error; this does not establish that secrets were found',
243
243
  };
244
244
  }
245
245
  }
@@ -0,0 +1,19 @@
1
+ # context-manager Examples — Anti-patterns vs ContextOS Standard
2
+
3
+ ## Example 1: Context Selection
4
+
5
+ ### Anti-pattern: Context Window Dumping
6
+
7
+ ```text
8
+ Agent reads all 180 files in src/ into context to debug a single button click handler.
9
+ Result: Exhausts 150k tokens, reaches rate limits, and forgets user instructions.
10
+ ```
11
+
12
+ ### Best practice: ContextOS Standard (Targeted AST Traversal)
13
+
14
+ ```text
15
+ 1. Inspect package.json and AGENTS.md.
16
+ 2. Grep for target symbol: grep_search for 'SubmitButton'.
17
+ 3. Read ONLY components/SubmitButton.tsx and its direct import types/button.ts.
18
+ Total tokens used: <1,500 tokens. Fast, accurate, zero hallucinations.
19
+ ```
@@ -116,32 +116,3 @@ Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
116
116
  ## Integration Notes
117
117
 
118
118
  How this skill interacts with other skills.
119
-
120
-
121
- # context-manager Examples — Anti-patterns vs ContextOS Standard
122
-
123
- ## Example 1: Context Selection
124
-
125
- ### Anti-pattern: Context Window Dumping
126
-
127
- ```text
128
- Agent reads all 180 files in src/ into context to debug a single button click handler.
129
- Result: Exhausts 150k tokens, reaches rate limits, and forgets user instructions.
130
- ```
131
-
132
- ### Best practice: ContextOS Standard (Targeted AST Traversal)
133
-
134
- ```text
135
- 1. Inspect package.json and AGENTS.md.
136
- 2. Grep for target symbol: grep_search for 'SubmitButton'.
137
- 3. Read ONLY components/SubmitButton.tsx and its direct import types/button.ts.
138
- Total tokens used: <1,500 tokens. Fast, accurate, zero hallucinations.
139
- ```
140
-
141
- # context-manager Troubleshooting & Common Mistakes
142
-
143
- ## 1. Token Budget Blowout
144
-
145
- - **Symptom**: Model performance drops significantly, losing earlier conversational context.
146
- - **Root Cause**: Loading large JSON mocks, lockfiles, or build directories into prompt.
147
- - **Fix**: Never read package-lock.json, dist/, or build artifacts unless explicitly debugging bundle outputs.
@@ -0,0 +1,7 @@
1
+ # context-manager Troubleshooting & Common Mistakes
2
+
3
+ ## 1. Token Budget Blowout
4
+
5
+ - **Symptom**: Model performance drops significantly, losing earlier conversational context.
6
+ - **Root Cause**: Loading large JSON mocks, lockfiles, or build directories into prompt.
7
+ - **Fix**: Never read package-lock.json, dist/, or build artifacts unless explicitly debugging bundle outputs.
@@ -0,0 +1,12 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "type": "object",
4
+ "properties": {
5
+ "rules_followed": {
6
+ "type": "boolean"
7
+ }
8
+ },
9
+ "required": [
10
+ "rules_followed"
11
+ ]
12
+ }