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.
- package/.agents/AGENTS.md +53 -396
- package/.agents/adapters/aider/export.js +11 -16
- package/.agents/adapters/claude/export.js +13 -13
- package/.agents/adapters/copilot/export.js +29 -8
- package/.agents/adapters/cursor/export.js +9 -18
- package/.agents/adapters/gemini/export.js +11 -46
- package/.agents/adapters/pure-compiler.js +65 -42
- package/.agents/adapters/shared.js +35 -1
- package/.agents/adapters/zed/export.js +2 -2
- package/.agents/compiled/registry.v2.json +30 -18
- package/.agents/compiled/registry.v2.sha256 +1 -1
- package/.agents/compiler/manifest-compiler.js +5 -29
- package/.agents/core/skills/context-os/references/project-graph.md +3 -3
- package/.agents/core/skills/engineering-workflow/SKILL.md +11 -316
- package/.agents/core/skills/engineering-workflow/references/workflow.md +336 -0
- package/.agents/core/skills/engineering-workflow/skill.yaml +2 -4
- package/.agents/core/skills/gstack-roles/SKILL.md +11 -128
- package/.agents/core/skills/gstack-roles/references/roles.md +149 -0
- package/.agents/core/skills/gstack-roles/skill.yaml +2 -4
- package/.agents/core/skills/ponytail-mindset/SKILL.md +13 -165
- package/.agents/core/skills/ponytail-mindset/references/minimalism.md +186 -0
- package/.agents/core/skills/ponytail-mindset/skill.yaml +2 -5
- package/.agents/core/skills/security/skill.yaml +1 -0
- package/.agents/ctx.js +22 -17
- package/.agents/customization-dx.js +13 -9
- package/.agents/doctor.js +2 -2
- package/.agents/generated/claude/skills/context-manager/EXAMPLES.md +19 -0
- package/.agents/generated/claude/skills/context-manager/SKILL.md +0 -29
- package/.agents/generated/claude/skills/context-manager/TROUBLESHOOTING.md +7 -0
- package/.agents/generated/claude/skills/context-manager/VALIDATION.json +12 -0
- package/.agents/generated/claude/skills/context-manager/references/context-rules.md +59 -0
- package/.agents/generated/claude/skills/context-os/EXAMPLES.md +21 -0
- package/.agents/generated/claude/skills/context-os/SKILL.md +0 -31
- package/.agents/generated/claude/skills/context-os/TROUBLESHOOTING.md +7 -0
- package/.agents/generated/claude/skills/context-os/VALIDATION.json +12 -0
- package/.agents/generated/claude/skills/context-os/packs.yaml +59 -0
- package/.agents/generated/claude/skills/context-os/references/context-rules.md +68 -0
- package/.agents/generated/claude/skills/context-os/references/pipeline.md +119 -0
- package/.agents/generated/claude/skills/context-os/references/project-graph.md +103 -0
- package/.agents/generated/claude/skills/context-os/rules.yaml +135 -0
- package/.agents/generated/claude/skills/engineering-workflow/EXAMPLES.md +57 -0
- package/.agents/generated/claude/skills/engineering-workflow/SKILL.md +10 -391
- package/.agents/generated/claude/skills/engineering-workflow/TROUBLESHOOTING.md +19 -0
- package/.agents/generated/claude/skills/engineering-workflow/VALIDATION.json +12 -0
- package/.agents/generated/claude/skills/engineering-workflow/references/workflow.md +336 -0
- package/.agents/generated/claude/skills/gemini-precision/EXAMPLES.md +72 -0
- package/.agents/generated/claude/skills/gemini-precision/SKILL.md +0 -100
- package/.agents/generated/claude/skills/gemini-precision/TROUBLESHOOTING.md +25 -0
- package/.agents/generated/claude/skills/gemini-precision/VALIDATION.json +12 -0
- package/.agents/generated/claude/skills/gstack-roles/EXAMPLES.md +23 -0
- package/.agents/generated/claude/skills/gstack-roles/SKILL.md +10 -164
- package/.agents/generated/claude/skills/gstack-roles/TROUBLESHOOTING.md +13 -0
- package/.agents/generated/claude/skills/gstack-roles/VALIDATION.json +12 -0
- package/.agents/generated/claude/skills/gstack-roles/references/roles.md +149 -0
- package/.agents/generated/claude/skills/ponytail-mindset/EXAMPLES.md +45 -0
- package/.agents/generated/claude/skills/ponytail-mindset/SKILL.md +12 -228
- package/.agents/generated/claude/skills/ponytail-mindset/TROUBLESHOOTING.md +19 -0
- package/.agents/generated/claude/skills/ponytail-mindset/VALIDATION.json +12 -0
- package/.agents/generated/claude/skills/ponytail-mindset/references/minimalism.md +186 -0
- package/.agents/generated/claude/skills/security/EXAMPLES.md +64 -0
- package/.agents/generated/claude/skills/security/SKILL.md +0 -86
- package/.agents/generated/claude/skills/security/TROUBLESHOOTING.md +19 -0
- package/.agents/generated/claude/skills/security/VALIDATION.json +12 -0
- package/.agents/generated/gemini/skills/context-manager/EXAMPLES.md +19 -0
- package/.agents/generated/gemini/skills/context-manager/SKILL.md +1 -33
- package/.agents/generated/gemini/skills/context-manager/TROUBLESHOOTING.md +7 -0
- package/.agents/generated/gemini/skills/context-manager/VALIDATION.json +12 -0
- package/.agents/generated/gemini/skills/context-manager/references/context-rules.md +59 -0
- package/.agents/generated/gemini/skills/context-os/EXAMPLES.md +21 -0
- package/.agents/generated/gemini/skills/context-os/SKILL.md +0 -35
- package/.agents/generated/gemini/skills/context-os/TROUBLESHOOTING.md +7 -0
- package/.agents/generated/gemini/skills/context-os/VALIDATION.json +12 -0
- package/.agents/generated/gemini/skills/context-os/packs.yaml +59 -0
- package/.agents/generated/gemini/skills/context-os/references/context-rules.md +68 -0
- package/.agents/generated/gemini/skills/context-os/references/pipeline.md +119 -0
- package/.agents/generated/gemini/skills/context-os/references/project-graph.md +103 -0
- package/.agents/generated/gemini/skills/context-os/rules.yaml +135 -0
- package/.agents/generated/gemini/skills/engineering-workflow/EXAMPLES.md +57 -0
- package/.agents/generated/gemini/skills/engineering-workflow/SKILL.md +11 -396
- package/.agents/generated/gemini/skills/engineering-workflow/TROUBLESHOOTING.md +19 -0
- package/.agents/generated/gemini/skills/engineering-workflow/VALIDATION.json +12 -0
- package/.agents/generated/gemini/skills/engineering-workflow/references/workflow.md +336 -0
- package/.agents/generated/gemini/skills/gemini-precision/EXAMPLES.md +72 -0
- package/.agents/generated/gemini/skills/gemini-precision/SKILL.md +0 -104
- package/.agents/generated/gemini/skills/gemini-precision/TROUBLESHOOTING.md +25 -0
- package/.agents/generated/gemini/skills/gemini-precision/VALIDATION.json +12 -0
- package/.agents/generated/gemini/skills/gstack-roles/EXAMPLES.md +23 -0
- package/.agents/generated/gemini/skills/gstack-roles/SKILL.md +11 -169
- package/.agents/generated/gemini/skills/gstack-roles/TROUBLESHOOTING.md +13 -0
- package/.agents/generated/gemini/skills/gstack-roles/VALIDATION.json +12 -0
- package/.agents/generated/gemini/skills/gstack-roles/references/roles.md +149 -0
- package/.agents/generated/gemini/skills/ponytail-mindset/EXAMPLES.md +45 -0
- package/.agents/generated/gemini/skills/ponytail-mindset/SKILL.md +13 -233
- package/.agents/generated/gemini/skills/ponytail-mindset/TROUBLESHOOTING.md +19 -0
- package/.agents/generated/gemini/skills/ponytail-mindset/VALIDATION.json +12 -0
- package/.agents/generated/gemini/skills/ponytail-mindset/references/minimalism.md +186 -0
- package/.agents/generated/gemini/skills/security/EXAMPLES.md +64 -0
- package/.agents/generated/gemini/skills/security/SKILL.md +2 -92
- package/.agents/generated/gemini/skills/security/TROUBLESHOOTING.md +19 -0
- package/.agents/generated/gemini/skills/security/VALIDATION.json +12 -0
- package/.agents/plugins.js +272 -28
- package/.agents/resolver/canonical-resolver.js +43 -7
- package/.agents/resolver/resolve-args.js +31 -0
- package/.agents/stats.js +8 -11
- package/.agents/workspace/workspace-graph.js +16 -6
- package/README.md +61 -6
- package/bin/index.js +157 -51
- package/bin/lib/ui.js +140 -0
- 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
|
-
|
|
10
|
+
Reduce unnecessary code and dependencies without weakening correctness or security.
|
|
14
11
|
|
|
15
12
|
## When to Use
|
|
16
13
|
|
|
17
|
-
|
|
14
|
+
Substantive implementation and refactoring during Build.
|
|
18
15
|
|
|
19
16
|
## Rules & Patterns
|
|
20
17
|
|
|
21
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
- [ ]
|
|
175
|
-
- [ ]
|
|
176
|
-
- [ ]
|
|
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
|
-
|
|
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
|
-
|
|
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
|
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>
|
|
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
|
|
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
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
const asJson =
|
|
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:
|
|
383
|
-
files,
|
|
384
|
-
explicitPhase:
|
|
385
|
-
contextBudgetTokens:
|
|
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
|
-
|
|
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
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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.
|