@sebasgc0399/agents-md 0.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/LICENSE +21 -0
- package/README.md +203 -0
- package/dist/cli.d.ts +6 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +128 -0
- package/dist/cli.js.map +1 -0
- package/dist/detect/command-detector.d.ts +6 -0
- package/dist/detect/command-detector.d.ts.map +1 -0
- package/dist/detect/command-detector.js +62 -0
- package/dist/detect/command-detector.js.map +1 -0
- package/dist/detect/folder-detector.d.ts +6 -0
- package/dist/detect/folder-detector.d.ts.map +1 -0
- package/dist/detect/folder-detector.js +69 -0
- package/dist/detect/folder-detector.js.map +1 -0
- package/dist/detect/framework-detector.d.ts +10 -0
- package/dist/detect/framework-detector.d.ts.map +1 -0
- package/dist/detect/framework-detector.js +121 -0
- package/dist/detect/framework-detector.js.map +1 -0
- package/dist/detect/index.d.ts +11 -0
- package/dist/detect/index.d.ts.map +1 -0
- package/dist/detect/index.js +70 -0
- package/dist/detect/index.js.map +1 -0
- package/dist/detect/package-detector.d.ts +6 -0
- package/dist/detect/package-detector.d.ts.map +1 -0
- package/dist/detect/package-detector.js +34 -0
- package/dist/detect/package-detector.js.map +1 -0
- package/dist/detect/runtime-detector.d.ts +6 -0
- package/dist/detect/runtime-detector.d.ts.map +1 -0
- package/dist/detect/runtime-detector.js +35 -0
- package/dist/detect/runtime-detector.js.map +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +15 -0
- package/dist/index.js.map +1 -0
- package/dist/render/data-builder.d.ts +9 -0
- package/dist/render/data-builder.d.ts.map +1 -0
- package/dist/render/data-builder.js +138 -0
- package/dist/render/data-builder.js.map +1 -0
- package/dist/render/index.d.ts +12 -0
- package/dist/render/index.d.ts.map +1 -0
- package/dist/render/index.js +29 -0
- package/dist/render/index.js.map +1 -0
- package/dist/render/mustache-renderer.d.ts +13 -0
- package/dist/render/mustache-renderer.d.ts.map +1 -0
- package/dist/render/mustache-renderer.js +51 -0
- package/dist/render/mustache-renderer.js.map +1 -0
- package/dist/render/validators.d.ts +9 -0
- package/dist/render/validators.d.ts.map +1 -0
- package/dist/render/validators.js +107 -0
- package/dist/render/validators.js.map +1 -0
- package/dist/templates/base.mustache +296 -0
- package/dist/templates/firebase.mustache +236 -0
- package/dist/templates/monorepo.mustache +253 -0
- package/dist/templates/react.mustache +231 -0
- package/dist/types.d.ts +112 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +5 -0
- package/dist/types.js.map +1 -0
- package/dist/utils/fs-utils.d.ts +20 -0
- package/dist/utils/fs-utils.d.ts.map +1 -0
- package/dist/utils/fs-utils.js +121 -0
- package/dist/utils/fs-utils.js.map +1 -0
- package/dist/utils/logger.d.ts +14 -0
- package/dist/utils/logger.d.ts.map +1 -0
- package/dist/utils/logger.js +32 -0
- package/dist/utils/logger.js.map +1 -0
- package/dist/utils/token-counter.d.ts +18 -0
- package/dist/utils/token-counter.d.ts.map +1 -0
- package/dist/utils/token-counter.js +45 -0
- package/dist/utils/token-counter.js.map +1 -0
- package/package.json +75 -0
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
## Propósito del repositorio
|
|
4
|
+
{{project_description}}
|
|
5
|
+
|
|
6
|
+
Este es un monorepo que contiene múltiples paquetes y aplicaciones.
|
|
7
|
+
|
|
8
|
+
## Tech stack
|
|
9
|
+
{{#stacks}}
|
|
10
|
+
- {{.}}
|
|
11
|
+
{{/stacks}}
|
|
12
|
+
|
|
13
|
+
## Estructura del monorepo
|
|
14
|
+
```
|
|
15
|
+
.
|
|
16
|
+
├── apps/ # Aplicaciones deployables
|
|
17
|
+
└── packages/ # Paquetes compartidos/librerías
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Comandos canónicos
|
|
21
|
+
- Instalar dependencias: `{{commands.install}}`
|
|
22
|
+
{{#has_dev}}
|
|
23
|
+
- Ejecutar todos los dev servers: `{{commands.dev}}`
|
|
24
|
+
{{/has_dev}}
|
|
25
|
+
{{#has_build}}
|
|
26
|
+
- Build todos los paquetes: `{{commands.build}}`
|
|
27
|
+
{{/has_build}}
|
|
28
|
+
{{#has_lint}}
|
|
29
|
+
- Lint todo el monorepo: `{{commands.lint}}`
|
|
30
|
+
{{/has_lint}}
|
|
31
|
+
{{#has_tests}}
|
|
32
|
+
- Tests de todo el monorepo: `{{commands.test}}`
|
|
33
|
+
{{/has_tests}}
|
|
34
|
+
|
|
35
|
+
### Comandos específicos de workspace
|
|
36
|
+
```bash
|
|
37
|
+
# Ejecutar comando en un workspace específico
|
|
38
|
+
npm run dev --workspace=apps/web
|
|
39
|
+
pnpm --filter @myorg/api dev
|
|
40
|
+
yarn workspace @myorg/shared test
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Definition of Done
|
|
44
|
+
Antes de considerar una tarea completa:
|
|
45
|
+
{{#has_tests}}
|
|
46
|
+
- [ ] `{{commands.test}}` pasa en todos los paquetes afectados
|
|
47
|
+
{{/has_tests}}
|
|
48
|
+
{{#has_lint}}
|
|
49
|
+
- [ ] `{{commands.lint}}` pasa sin errores
|
|
50
|
+
{{/has_lint}}
|
|
51
|
+
{{#has_build}}
|
|
52
|
+
- [ ] `{{commands.build}}` completa sin errores
|
|
53
|
+
{{/has_build}}
|
|
54
|
+
- [ ] Cambios en packages/ no rompen apps/ que dependen de ellos
|
|
55
|
+
- [ ] Versiones de dependencias sincronizadas (usar workspaces)
|
|
56
|
+
- [ ] No añadir dependencias nuevas sin confirmación
|
|
57
|
+
|
|
58
|
+
## Estilo y convenciones
|
|
59
|
+
{{style_notes}}
|
|
60
|
+
|
|
61
|
+
### Organización de código
|
|
62
|
+
- **apps/**: Aplicaciones completas (web, mobile, admin)
|
|
63
|
+
- **packages/**: Librerías compartidas, configuraciones, utilidades
|
|
64
|
+
- Naming: `@org/package-name` para scoped packages
|
|
65
|
+
|
|
66
|
+
### Dependencias
|
|
67
|
+
- Dependencias compartidas declaradas en root package.json
|
|
68
|
+
- Dependencias específicas en cada workspace
|
|
69
|
+
- Usar workspaces protocol para dependencias internas: `"@myorg/shared": "workspace:*"`
|
|
70
|
+
|
|
71
|
+
{{#has_tests}}
|
|
72
|
+
## Testing guidelines
|
|
73
|
+
{{testing_notes}}
|
|
74
|
+
|
|
75
|
+
### Estrategia de testing en monorepo
|
|
76
|
+
- Tests unitarios en cada package
|
|
77
|
+
- Tests de integración para apps que consumen packages
|
|
78
|
+
- Usar cache de tests para evitar re-ejecutar tests innecesarios
|
|
79
|
+
{{/has_tests}}
|
|
80
|
+
|
|
81
|
+
{{#isStandardOrFull}}
|
|
82
|
+
## How to work with AI agents
|
|
83
|
+
|
|
84
|
+
### Task format
|
|
85
|
+
- Define target workspaces and expected outcome.
|
|
86
|
+
- List touched apps/packages before implementation.
|
|
87
|
+
- Keep scope isolated to impacted graph nodes.
|
|
88
|
+
- Ask for explicit verification across affected workspaces.
|
|
89
|
+
|
|
90
|
+
### Requesting diffs and validation
|
|
91
|
+
- Ask for per-workspace change summary.
|
|
92
|
+
- Ask for exact commands and workspace filters used.
|
|
93
|
+
- Ask for dependency-graph impact notes.
|
|
94
|
+
- Ask for test/build results for impacted packages.
|
|
95
|
+
|
|
96
|
+
### Monorepo delivery checklist
|
|
97
|
+
- Confirm no unintended cross-workspace API breaks.
|
|
98
|
+
- Confirm package boundaries are respected.
|
|
99
|
+
- Confirm workspace scripts remain canonical.
|
|
100
|
+
- Confirm lockfile and workspace metadata consistency.
|
|
101
|
+
|
|
102
|
+
## Expanded Definition of Done
|
|
103
|
+
- [ ] Scope complete in affected workspaces only.
|
|
104
|
+
- [ ] Builds/tests pass for impacted graph nodes.
|
|
105
|
+
- [ ] No placeholder values in generated markdown.
|
|
106
|
+
- [ ] Consumer apps validated for shared package changes.
|
|
107
|
+
- [ ] Documentation updated for workspace-level behavior changes.
|
|
108
|
+
|
|
109
|
+
## Debug checklist
|
|
110
|
+
- Reproduce with filtered command for one workspace first.
|
|
111
|
+
- Validate workspace command detection from root scripts.
|
|
112
|
+
- Check generated output for required monorepo sections.
|
|
113
|
+
- Confirm profile-specific size limits are respected.
|
|
114
|
+
- Re-run focused tests before full repo suite.
|
|
115
|
+
|
|
116
|
+
## Testing strategy
|
|
117
|
+
- Keep tests targeted with workspace filters where possible.
|
|
118
|
+
- Prioritize regression tests on shared packages.
|
|
119
|
+
- Use deterministic fixtures for command/render behavior.
|
|
120
|
+
{{#has_tests}}
|
|
121
|
+
- Keep command references aligned with `{{commands.test}}`.
|
|
122
|
+
{{/has_tests}}
|
|
123
|
+
|
|
124
|
+
## Do / Don't
|
|
125
|
+
### Do
|
|
126
|
+
- Do keep shared package APIs stable and explicit.
|
|
127
|
+
- Do isolate changes by workspace when possible.
|
|
128
|
+
- Do document dependency graph impact.
|
|
129
|
+
- Do preserve default compact behavior.
|
|
130
|
+
|
|
131
|
+
### Don't
|
|
132
|
+
- Don't change root scripts without clear reason.
|
|
133
|
+
- Don't introduce hidden coupling between workspaces.
|
|
134
|
+
- Don't skip impacted consumer validation.
|
|
135
|
+
- Don't mix unrelated workspace refactors.
|
|
136
|
+
|
|
137
|
+
## Agent handoff template
|
|
138
|
+
### Required fields
|
|
139
|
+
- Goal: one sentence describing expected final state.
|
|
140
|
+
- Scope: exact files or folders that can change.
|
|
141
|
+
- Constraints: what must not change.
|
|
142
|
+
- Validation: commands that prove the change.
|
|
143
|
+
- Risks: known uncertainty or follow-up items.
|
|
144
|
+
|
|
145
|
+
### Status update format
|
|
146
|
+
- Completed: concrete items done.
|
|
147
|
+
- In progress: current active step.
|
|
148
|
+
- Next: immediate next action.
|
|
149
|
+
- Blockers: missing info or external dependency.
|
|
150
|
+
|
|
151
|
+
### Review checklist
|
|
152
|
+
- [ ] File-level diff is easy to follow.
|
|
153
|
+
- [ ] Tests cover changed behavior.
|
|
154
|
+
- [ ] Output remains deterministic.
|
|
155
|
+
- [ ] No hidden behavior changes.
|
|
156
|
+
- [ ] Error handling is explicit.
|
|
157
|
+
- [ ] Documentation reflects new behavior.
|
|
158
|
+
|
|
159
|
+
### Escalation rules
|
|
160
|
+
- Escalate when requirements conflict.
|
|
161
|
+
- Escalate before adding dependencies.
|
|
162
|
+
- Escalate before touching unrelated modules.
|
|
163
|
+
- Escalate on ambiguous security implications.
|
|
164
|
+
{{/isStandardOrFull}}
|
|
165
|
+
|
|
166
|
+
{{#isFull}}
|
|
167
|
+
## Advanced agent protocol
|
|
168
|
+
|
|
169
|
+
### Risk classification
|
|
170
|
+
- Low: docs/template-only edits.
|
|
171
|
+
- Medium: profile-gated sections and validator ranges.
|
|
172
|
+
- High: script detection, workspace command rendering, file writes.
|
|
173
|
+
- Require targeted tests for medium/high changes.
|
|
174
|
+
|
|
175
|
+
### PR handoff checklist
|
|
176
|
+
- Include before/after output for compact/standard/full.
|
|
177
|
+
- Include verification commands with workspace filters.
|
|
178
|
+
- Include compatibility statement for existing root commands.
|
|
179
|
+
- Include residual risk and rollback notes.
|
|
180
|
+
|
|
181
|
+
### Failure triage flow
|
|
182
|
+
1. Reproduce with fixture and explicit profile.
|
|
183
|
+
2. Isolate detect/render/validate stage.
|
|
184
|
+
3. Verify workspace command extraction assumptions.
|
|
185
|
+
4. Apply minimal patch and add regression coverage.
|
|
186
|
+
|
|
187
|
+
### CI hardening notes
|
|
188
|
+
- Keep commands shell-neutral where possible.
|
|
189
|
+
- Keep path handling OS-neutral.
|
|
190
|
+
- Keep tests deterministic with fixed fixtures.
|
|
191
|
+
- Avoid flaky ordering assumptions in assertions.
|
|
192
|
+
|
|
193
|
+
### Verification matrix
|
|
194
|
+
| Layer | Check | Evidence |
|
|
195
|
+
|---|---|---|
|
|
196
|
+
| CLI | Arg parsing | command output |
|
|
197
|
+
| Detection | scripts/framework | fixture result |
|
|
198
|
+
| Rendering | profile sections | markdown preview |
|
|
199
|
+
| Validation | limits/placeholders | unit tests |
|
|
200
|
+
| E2E | dry-run command | test pass |
|
|
201
|
+
|
|
202
|
+
### Rollback playbook
|
|
203
|
+
1. Revert profile-specific template blocks first.
|
|
204
|
+
2. Keep parser support only if backward compatible.
|
|
205
|
+
3. Re-run compact profile tests and e2e.
|
|
206
|
+
4. Re-introduce changes in smaller slices.
|
|
207
|
+
|
|
208
|
+
### Communication protocol
|
|
209
|
+
- Summarize assumptions before coding.
|
|
210
|
+
- Report changed files immediately after edit step.
|
|
211
|
+
- Report executed commands and outcomes.
|
|
212
|
+
- Report unresolved risks before handoff.
|
|
213
|
+
|
|
214
|
+
### Post-merge audit
|
|
215
|
+
- Verify README examples still run as documented.
|
|
216
|
+
- Verify SPEC and behavior remain aligned.
|
|
217
|
+
- Verify CI pass on at least one Windows runner.
|
|
218
|
+
- Verify default compact output remains unchanged.
|
|
219
|
+
- Verify standard/full remain within configured limits.
|
|
220
|
+
|
|
221
|
+
### Minimal failure report template
|
|
222
|
+
- Command: exact failing command
|
|
223
|
+
- Expected: what should happen
|
|
224
|
+
- Actual: what happened
|
|
225
|
+
- Suspected layer: detect/render/validate/cli
|
|
226
|
+
- Reproduction fixture: path used
|
|
227
|
+
|
|
228
|
+
### Final release gate
|
|
229
|
+
- Confirm profile-specific limits pass validator.
|
|
230
|
+
- Confirm placeholder checks remain strict.
|
|
231
|
+
- Confirm default compact output is unchanged.
|
|
232
|
+
- Confirm docs match implemented flags.
|
|
233
|
+
- Confirm test suite is green in CI mode.
|
|
234
|
+
- Confirm no unrelated files changed.
|
|
235
|
+
- Confirm generated markdown still starts with # AGENTS.
|
|
236
|
+
- Confirm profile ordering full > standard > compact.
|
|
237
|
+
{{/isFull}}
|
|
238
|
+
|
|
239
|
+
## Seguridad
|
|
240
|
+
{{security_notes}}
|
|
241
|
+
|
|
242
|
+
### Monorepo-specific
|
|
243
|
+
- Revisar todas las dependencias transitivas (usar `npm audit` o `pnpm audit`)
|
|
244
|
+
- Lockfile sincronizado en root (yarn.lock, pnpm-lock.yaml)
|
|
245
|
+
- No exponer secrets entre workspaces innecesariamente
|
|
246
|
+
|
|
247
|
+
## Build y Deploy
|
|
248
|
+
- Build incremental: solo rebuilds paquetes modificados
|
|
249
|
+
- Topological ordering: packages se buildan en orden de dependencias
|
|
250
|
+
- Cache de builds para optimizar CI/CD
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
*Generated by agents-md v0.1.0*
|
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
## Propósito del repositorio
|
|
4
|
+
{{project_description}}
|
|
5
|
+
|
|
6
|
+
## Tech stack
|
|
7
|
+
{{#stacks}}
|
|
8
|
+
- {{.}}
|
|
9
|
+
{{/stacks}}
|
|
10
|
+
|
|
11
|
+
## Comandos canónicos
|
|
12
|
+
- Instalar dependencias: `{{commands.install}}`
|
|
13
|
+
{{#has_dev}}
|
|
14
|
+
- Ejecutar en local: `{{commands.dev}}`
|
|
15
|
+
{{/has_dev}}
|
|
16
|
+
{{#has_build}}
|
|
17
|
+
- Build: `{{commands.build}}`
|
|
18
|
+
{{/has_build}}
|
|
19
|
+
{{#has_lint}}
|
|
20
|
+
- Lint: `{{commands.lint}}`
|
|
21
|
+
{{/has_lint}}
|
|
22
|
+
{{#has_format}}
|
|
23
|
+
- Format: `{{commands.format}}`
|
|
24
|
+
{{/has_format}}
|
|
25
|
+
{{#has_tests}}
|
|
26
|
+
- Tests: `{{commands.test}}`
|
|
27
|
+
{{/has_tests}}
|
|
28
|
+
|
|
29
|
+
## Definition of Done
|
|
30
|
+
Antes de considerar una tarea completa:
|
|
31
|
+
{{#has_tests}}
|
|
32
|
+
- [ ] `{{commands.test}}` pasa sin errores
|
|
33
|
+
{{/has_tests}}
|
|
34
|
+
{{#has_lint}}
|
|
35
|
+
- [ ] `{{commands.lint}}` pasa sin errores
|
|
36
|
+
{{/has_lint}}
|
|
37
|
+
- [ ] No añadir dependencias nuevas sin confirmación
|
|
38
|
+
- [ ] Componentes no tienen warnings de React
|
|
39
|
+
- [ ] Documentar props de componentes exportados
|
|
40
|
+
|
|
41
|
+
## Estilo y convenciones
|
|
42
|
+
{{style_notes}}
|
|
43
|
+
|
|
44
|
+
### Estructura de componentes
|
|
45
|
+
- Un componente por archivo
|
|
46
|
+
- Archivo nombrado igual que el componente exportado (PascalCase)
|
|
47
|
+
- Exports nombrados para componentes, default para páginas
|
|
48
|
+
|
|
49
|
+
### Gestión de estado
|
|
50
|
+
- State local con `useState` para UI state
|
|
51
|
+
- Props drilling evitado con Context API o state management library
|
|
52
|
+
- Side effects con `useEffect`, memoización con `useMemo`/`useCallback` cuando sea necesario
|
|
53
|
+
|
|
54
|
+
{{#has_tests}}
|
|
55
|
+
## Testing guidelines
|
|
56
|
+
{{testing_notes}}
|
|
57
|
+
|
|
58
|
+
### Cobertura esperada
|
|
59
|
+
- Componentes: interacciones de usuario, renderizado condicional
|
|
60
|
+
- Hooks personalizados: lógica de negocio
|
|
61
|
+
- Utils: funciones puras con casos edge
|
|
62
|
+
{{/has_tests}}
|
|
63
|
+
|
|
64
|
+
{{#isStandardOrFull}}
|
|
65
|
+
## How to work with AI agents
|
|
66
|
+
|
|
67
|
+
### Task format
|
|
68
|
+
- Start with a short scope statement and expected result.
|
|
69
|
+
- Name target files before implementation.
|
|
70
|
+
- Include constraints (no extra deps, keep ESM, deterministic output).
|
|
71
|
+
- Ask for acceptance criteria in testable terms.
|
|
72
|
+
|
|
73
|
+
### Requesting diffs and validation
|
|
74
|
+
- Request file-level summary and reason per file.
|
|
75
|
+
- Ask for exact commands used for validation.
|
|
76
|
+
- Ask for test totals (files/tests passed).
|
|
77
|
+
- Ask for explicit mention of tradeoffs.
|
|
78
|
+
|
|
79
|
+
### React delivery checklist
|
|
80
|
+
- Keep component contracts stable unless scope requires change.
|
|
81
|
+
- Confirm hooks order is preserved.
|
|
82
|
+
- Validate props and event naming consistency.
|
|
83
|
+
- Keep rendering behavior deterministic.
|
|
84
|
+
|
|
85
|
+
## Expanded Definition of Done
|
|
86
|
+
- [ ] Feature scope complete with minimal diff.
|
|
87
|
+
- [ ] No React warnings introduced in dev/test output.
|
|
88
|
+
- [ ] Shared components remain backward compatible.
|
|
89
|
+
- [ ] Generated AGENTS content has no placeholders.
|
|
90
|
+
- [ ] Docs and tests reflect behavior changes.
|
|
91
|
+
|
|
92
|
+
## Debug checklist
|
|
93
|
+
- Reproduce issue with the smallest fixture.
|
|
94
|
+
- Verify canonical commands first (`dev`, `build`, `test`, `lint`).
|
|
95
|
+
- Check path handling and platform neutrality.
|
|
96
|
+
- Validate generated markdown for required sections.
|
|
97
|
+
- Re-run focused tests before full test suite.
|
|
98
|
+
|
|
99
|
+
## Testing strategy
|
|
100
|
+
- Prioritize unit tests for render and validation logic.
|
|
101
|
+
- Keep e2e tests focused on one deterministic CLI flow.
|
|
102
|
+
- Assert key lines, not entire snapshots.
|
|
103
|
+
{{#has_tests}}
|
|
104
|
+
- Keep command examples aligned with `{{commands.test}}`.
|
|
105
|
+
{{/has_tests}}
|
|
106
|
+
|
|
107
|
+
## Do / Don't
|
|
108
|
+
### Do
|
|
109
|
+
- Do keep components readable and narrowly scoped.
|
|
110
|
+
- Do prefer explicit conditions in templates.
|
|
111
|
+
- Do report behavior changes with concrete examples.
|
|
112
|
+
- Do preserve default profile behavior.
|
|
113
|
+
|
|
114
|
+
### Don't
|
|
115
|
+
- Don't couple tests to OS-specific path formats.
|
|
116
|
+
- Don't introduce hidden side effects in renderers.
|
|
117
|
+
- Don't use placeholders as runtime fallbacks in final output.
|
|
118
|
+
- Don't grow scope beyond requested profile behavior.
|
|
119
|
+
|
|
120
|
+
## Agent handoff template
|
|
121
|
+
### Required fields
|
|
122
|
+
- Goal: one sentence describing expected final state.
|
|
123
|
+
- Scope: exact files or folders that can change.
|
|
124
|
+
- Constraints: what must not change.
|
|
125
|
+
- Validation: commands that prove the change.
|
|
126
|
+
- Risks: known uncertainty or follow-up items.
|
|
127
|
+
|
|
128
|
+
### Status update format
|
|
129
|
+
- Completed: concrete items done.
|
|
130
|
+
- In progress: current active step.
|
|
131
|
+
- Next: immediate next action.
|
|
132
|
+
- Blockers: missing info or external dependency.
|
|
133
|
+
|
|
134
|
+
### Review checklist
|
|
135
|
+
- [ ] File-level diff is easy to follow.
|
|
136
|
+
- [ ] Tests cover changed behavior.
|
|
137
|
+
- [ ] Output remains deterministic.
|
|
138
|
+
- [ ] No hidden behavior changes.
|
|
139
|
+
- [ ] Error handling is explicit.
|
|
140
|
+
- [ ] Documentation reflects new behavior.
|
|
141
|
+
|
|
142
|
+
### Escalation rules
|
|
143
|
+
- Escalate when requirements conflict.
|
|
144
|
+
- Escalate before adding dependencies.
|
|
145
|
+
- Escalate before touching unrelated modules.
|
|
146
|
+
- Escalate on ambiguous security implications.
|
|
147
|
+
{{/isStandardOrFull}}
|
|
148
|
+
|
|
149
|
+
{{#isFull}}
|
|
150
|
+
## Advanced agent protocol
|
|
151
|
+
|
|
152
|
+
### Review depth by risk
|
|
153
|
+
- Low: wording/layout-only changes in templates.
|
|
154
|
+
- Medium: profile-gated content and validator thresholds.
|
|
155
|
+
- High: CLI option parsing and output file writes.
|
|
156
|
+
- Require targeted regression tests for medium/high changes.
|
|
157
|
+
|
|
158
|
+
### PR handoff checklist
|
|
159
|
+
- Include before/after output examples for each profile.
|
|
160
|
+
- Include exact commands run locally.
|
|
161
|
+
- Include compatibility statement for default `compact`.
|
|
162
|
+
- Include residual risk notes.
|
|
163
|
+
|
|
164
|
+
### Incident response quick flow
|
|
165
|
+
1. Reproduce with fixture and explicit profile flag.
|
|
166
|
+
2. Verify detection output before template rendering.
|
|
167
|
+
3. Confirm validator behavior matches selected profile limits.
|
|
168
|
+
4. Patch with minimal diff and add coverage.
|
|
169
|
+
|
|
170
|
+
### CI hardening notes
|
|
171
|
+
- Avoid shell-dependent command execution in tests.
|
|
172
|
+
- Use `process.execPath` and argument arrays.
|
|
173
|
+
- Use `path.join`/`path.resolve` consistently.
|
|
174
|
+
- Keep tests deterministic and fast.
|
|
175
|
+
|
|
176
|
+
### Verification matrix
|
|
177
|
+
| Layer | Check | Evidence |
|
|
178
|
+
|---|---|---|
|
|
179
|
+
| CLI | Arg parsing | command output |
|
|
180
|
+
| Detection | scripts/framework | fixture result |
|
|
181
|
+
| Rendering | profile sections | markdown preview |
|
|
182
|
+
| Validation | limits/placeholders | unit tests |
|
|
183
|
+
| E2E | dry-run command | test pass |
|
|
184
|
+
|
|
185
|
+
### Rollback playbook
|
|
186
|
+
1. Revert profile-specific template blocks first.
|
|
187
|
+
2. Keep parser support only if backward compatible.
|
|
188
|
+
3. Re-run compact profile tests and e2e.
|
|
189
|
+
4. Re-introduce changes in smaller slices.
|
|
190
|
+
|
|
191
|
+
### Communication protocol
|
|
192
|
+
- Summarize assumptions before coding.
|
|
193
|
+
- Report changed files immediately after edit step.
|
|
194
|
+
- Report executed commands and outcomes.
|
|
195
|
+
- Report unresolved risks before handoff.
|
|
196
|
+
|
|
197
|
+
### Post-merge audit
|
|
198
|
+
- Verify README examples still run as documented.
|
|
199
|
+
- Verify SPEC and behavior remain aligned.
|
|
200
|
+
- Verify CI pass on at least one Windows runner.
|
|
201
|
+
- Verify default compact output remains unchanged.
|
|
202
|
+
- Verify standard/full remain within configured limits.
|
|
203
|
+
|
|
204
|
+
### Minimal failure report template
|
|
205
|
+
- Command: exact failing command
|
|
206
|
+
- Expected: what should happen
|
|
207
|
+
- Actual: what happened
|
|
208
|
+
- Suspected layer: detect/render/validate/cli
|
|
209
|
+
- Reproduction fixture: path used
|
|
210
|
+
|
|
211
|
+
### Final release gate
|
|
212
|
+
- Confirm profile-specific limits pass validator.
|
|
213
|
+
- Confirm placeholder checks remain strict.
|
|
214
|
+
- Confirm default compact output is unchanged.
|
|
215
|
+
- Confirm docs match implemented flags.
|
|
216
|
+
- Confirm test suite is green in CI mode.
|
|
217
|
+
- Confirm no unrelated files changed.
|
|
218
|
+
- Confirm generated markdown still starts with # AGENTS.
|
|
219
|
+
- Confirm profile ordering full > standard > compact.
|
|
220
|
+
{{/isFull}}
|
|
221
|
+
|
|
222
|
+
## Seguridad
|
|
223
|
+
{{security_notes}}
|
|
224
|
+
|
|
225
|
+
### React-specific
|
|
226
|
+
- Sanitizar inputs antes de usar `dangerouslySetInnerHTML`
|
|
227
|
+
- Validar props con PropTypes o TypeScript
|
|
228
|
+
- No exponer API keys en código cliente
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
*Generated by agents-md v0.1.0*
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Core type definitions for agents-md CLI
|
|
3
|
+
*/
|
|
4
|
+
export interface CLIOptions {
|
|
5
|
+
out: string;
|
|
6
|
+
force: boolean;
|
|
7
|
+
dryRun: boolean;
|
|
8
|
+
yes: boolean;
|
|
9
|
+
interactive: boolean;
|
|
10
|
+
template?: string;
|
|
11
|
+
verbose: boolean;
|
|
12
|
+
profile: Profile;
|
|
13
|
+
}
|
|
14
|
+
export type WorkspaceConfig = string[] | {
|
|
15
|
+
packages?: string[];
|
|
16
|
+
};
|
|
17
|
+
export interface PackageInfo {
|
|
18
|
+
name: string;
|
|
19
|
+
version?: string;
|
|
20
|
+
description?: string;
|
|
21
|
+
type?: 'module' | 'commonjs';
|
|
22
|
+
scripts: Record<string, string>;
|
|
23
|
+
dependencies: Record<string, string>;
|
|
24
|
+
devDependencies: Record<string, string>;
|
|
25
|
+
engines?: Record<string, string>;
|
|
26
|
+
workspaces?: WorkspaceConfig;
|
|
27
|
+
}
|
|
28
|
+
export interface FolderStructure {
|
|
29
|
+
hasSrc: boolean;
|
|
30
|
+
hasFunctions: boolean;
|
|
31
|
+
hasTests: boolean;
|
|
32
|
+
hasApps: boolean;
|
|
33
|
+
hasPackages: boolean;
|
|
34
|
+
hasPublic: boolean;
|
|
35
|
+
hasDocs: boolean;
|
|
36
|
+
isMonorepo: boolean;
|
|
37
|
+
folders: string[];
|
|
38
|
+
}
|
|
39
|
+
export type FrameworkType = 'react' | 'vue' | 'angular' | 'svelte' | 'next' | 'nuxt' | 'express' | 'fastify' | 'firebase-functions' | 'unknown';
|
|
40
|
+
export interface FrameworkInfo {
|
|
41
|
+
type: FrameworkType;
|
|
42
|
+
version?: string;
|
|
43
|
+
confidence: 'high' | 'medium' | 'low';
|
|
44
|
+
indicators: string[];
|
|
45
|
+
}
|
|
46
|
+
export type RuntimeType = 'node' | 'bun' | 'unknown';
|
|
47
|
+
export type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun' | 'unknown';
|
|
48
|
+
export type Profile = 'compact' | 'standard' | 'full';
|
|
49
|
+
export interface RuntimeInfo {
|
|
50
|
+
type: RuntimeType;
|
|
51
|
+
version?: string;
|
|
52
|
+
packageManager: PackageManager;
|
|
53
|
+
}
|
|
54
|
+
export interface CanonicalCommands {
|
|
55
|
+
install: string;
|
|
56
|
+
dev: string | null;
|
|
57
|
+
build: string | null;
|
|
58
|
+
test: string | null;
|
|
59
|
+
lint: string | null;
|
|
60
|
+
format: string | null;
|
|
61
|
+
}
|
|
62
|
+
export interface DetectionResult {
|
|
63
|
+
packageInfo: PackageInfo | null;
|
|
64
|
+
folderStructure: FolderStructure;
|
|
65
|
+
framework: FrameworkInfo;
|
|
66
|
+
runtime: RuntimeInfo;
|
|
67
|
+
commands: CanonicalCommands;
|
|
68
|
+
confidence: 'high' | 'medium' | 'low';
|
|
69
|
+
}
|
|
70
|
+
export interface TemplateContext {
|
|
71
|
+
project_name: string;
|
|
72
|
+
project_description: string;
|
|
73
|
+
profile: Profile;
|
|
74
|
+
stacks: string[];
|
|
75
|
+
commands: {
|
|
76
|
+
install: string;
|
|
77
|
+
dev: string;
|
|
78
|
+
lint: string;
|
|
79
|
+
format: string;
|
|
80
|
+
test: string;
|
|
81
|
+
build: string;
|
|
82
|
+
};
|
|
83
|
+
style_notes: string;
|
|
84
|
+
testing_notes: string;
|
|
85
|
+
security_notes: string;
|
|
86
|
+
has_dev: boolean;
|
|
87
|
+
has_tests: boolean;
|
|
88
|
+
has_lint: boolean;
|
|
89
|
+
has_format: boolean;
|
|
90
|
+
has_build: boolean;
|
|
91
|
+
is_monorepo: boolean;
|
|
92
|
+
isCompact: boolean;
|
|
93
|
+
isStandard: boolean;
|
|
94
|
+
isFull: boolean;
|
|
95
|
+
isStandardOrFull: boolean;
|
|
96
|
+
is_unknown_generic?: boolean;
|
|
97
|
+
framework_type: string;
|
|
98
|
+
runtime_type: string;
|
|
99
|
+
}
|
|
100
|
+
export interface ValidationResult {
|
|
101
|
+
valid: boolean;
|
|
102
|
+
warnings: string[];
|
|
103
|
+
errors: string[];
|
|
104
|
+
lineCount: number;
|
|
105
|
+
estimatedTokens: number;
|
|
106
|
+
}
|
|
107
|
+
export interface GenerationResult {
|
|
108
|
+
content: string;
|
|
109
|
+
validation: ValidationResult;
|
|
110
|
+
detection: DetectionResult;
|
|
111
|
+
}
|
|
112
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Safe file system utilities
|
|
3
|
+
*/
|
|
4
|
+
/**
|
|
5
|
+
* Safely read package.json with size limit (1MB max)
|
|
6
|
+
*/
|
|
7
|
+
export declare function readPackageJson(rootPath: string): Promise<unknown>;
|
|
8
|
+
/**
|
|
9
|
+
* Check if a directory exists
|
|
10
|
+
*/
|
|
11
|
+
export declare function directoryExists(dirPath: string): boolean;
|
|
12
|
+
/**
|
|
13
|
+
* Check if a file exists
|
|
14
|
+
*/
|
|
15
|
+
export declare function fileExists(filePath: string): boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Check if path is within project (prevent path traversal)
|
|
18
|
+
*/
|
|
19
|
+
export declare function isPathSafe(basePath: string, targetPath: string): boolean;
|
|
20
|
+
//# sourceMappingURL=fs-utils.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fs-utils.d.ts","sourceRoot":"","sources":["../../src/utils/fs-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;GAEG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAsBxE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMxD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAsBxE"}
|