@sebasgc0399/agents-md 0.2.0

package/dist/render/mustache-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mustache-renderer.js","sourceRoot":"","sources":["../../src/render/mustache-renderer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,QAAQ,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAGpC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAE3C;;GAEG;AACH,SAAS,YAAY,CAAC,YAAoB;IACxC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAE3E,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,uBAAuB,YAAY,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,OAAwB;IAExB,MAAM,QAAQ,GAAG,YAAY,CAAC,YAAY,CAAC,CAAC;IAE5C,wDAAwD;IACxD,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;IAEjC,OAAO,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAwB;IACrD,gCAAgC;IAChC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IAED,+BAA+B;IAC/B,QAAQ,OAAO,CAAC,cAAc,EAAE,CAAC;QAC/B,KAAK,OAAO,CAAC;QACb,KAAK,MAAM;YACT,OAAO,gBAAgB,CAAC;QAE1B,KAAK,KAAK,CAAC;QACX,KAAK,MAAM;YACT,OAAO,eAAe,CAAC,CAAC,kDAAkD;QAE5E,KAAK,oBAAoB;YACvB,OAAO,mBAAmB,CAAC;QAE7B;YACE,OAAO,eAAe,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/dist/render/validators.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Output validation
+ */
+import { Profile, ValidationResult } from '../types.js';
+/**
+ * Validate generated AGENTS.md content
+ */
+export declare function validateOutput(content: string, profile?: Profile): ValidationResult;
+//# sourceMappingURL=validators.d.ts.map

package/dist/render/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../../src/render/validators.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA2BxD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,OAAmB,GAC3B,gBAAgB,CAgGlB"}

package/dist/render/validators.js

@@ -0,0 +1,107 @@
+/**
+ * Output validation
+ */
+import { estimateTokens } from '../utils/token-counter.js';
+const PROFILE_LIMITS = {
+    compact: {
+        minLines: 50,
+        maxLines: 110,
+        minTokens: 0,
+        maxTokens: 900,
+    },
+    standard: {
+        minLines: 150,
+        maxLines: 230,
+        minTokens: 0,
+        maxTokens: 1600,
+    },
+    full: {
+        minLines: 220,
+        maxLines: 360,
+        minTokens: 0,
+        maxTokens: 2400,
+    },
+};
+/**
+ * Validate generated AGENTS.md content
+ */
+export function validateOutput(content, profile = 'compact') {
+    const normalized = content.replace(/\r\n/g, '\n');
+    const normalizedForCount = normalized.replace(/\n+$/g, '');
+    const lines = normalizedForCount.length ? normalizedForCount.split('\n') : [''];
+    const lineCount = lines.length;
+    const estimatedTokens = estimateTokens(normalized);
+    const limits = PROFILE_LIMITS[profile];
+    const warnings = [];
+    const errors = [];
+    // Line count validation (profile-specific targets)
+    if (lineCount < limits.minLines) {
+        warnings.push(`Output is quite short (${lineCount} lines). Target for ${profile}: ` +
+            `${limits.minLines}-${limits.maxLines} lines.`);
+    }
+    else if (lineCount > limits.maxLines) {
+        warnings.push(`Output is too long (${lineCount} lines). Target for ${profile}: ` +
+            `${limits.minLines}-${limits.maxLines} lines.`);
+    }
+    // Token count validation (profile-specific targets)
+    if (limits.minTokens > 0 && estimatedTokens < limits.minTokens) {
+        warnings.push(`Only ${estimatedTokens} tokens (target for ${profile}: ` +
+            `${limits.minTokens}-${limits.maxTokens}). Consider adding more details.`);
+    }
+    else if (estimatedTokens > limits.maxTokens) {
+        warnings.push(`${estimatedTokens} tokens exceeds budget for ${profile} (max: ${limits.maxTokens}). ` +
+            'AI agents may not process it efficiently.');
+    }
+    // Check for placeholder tokens that shouldn't be in output
+    const forbiddenPlaceholders = [
+        { token: 'undefined', pattern: /\bundefined\b/ },
+        { token: 'null', pattern: /\bnull\b/ },
+    ];
+    for (const { token, pattern } of forbiddenPlaceholders) {
+        if (pattern.test(normalized)) {
+            errors.push(`Output contains forbidden placeholder string: "${token}"`);
+        }
+    }
+    // Check for N/A commands (should use conditional rendering instead)
+    const naCount = (normalized.match(/`N\/A`/g) || []).length;
+    if (naCount > 0) {
+        warnings.push(`Found ${naCount} N/A placeholder(s). Consider hiding missing commands.`);
+    }
+    // Check for empty level-2 sections (ignore level-3 headings as boundaries).
+    const headingRegex = /^##\s+.+$/gm;
+    const headings = Array.from(normalized.matchAll(headingRegex));
+    for (let i = 0; i < headings.length; i++) {
+        const heading = headings[i];
+        const headingIndex = heading.index;
+        if (headingIndex === undefined) {
+            continue;
+        }
+        const headingLine = heading[0];
+        const start = headingIndex;
+        const end = headings[i + 1]?.index ?? normalized.length;
+        const sectionBody = normalized.slice(start + headingLine.length, end);
+        const hasMeaningfulLine = sectionBody.split('\n').some(line => {
+            const trimmed = line.trim();
+            if (trimmed === '') {
+                return false;
+            }
+            if (/^<!--.*-->$/.test(trimmed)) {
+                return false;
+            }
+            return true;
+        });
+        if (!hasMeaningfulLine) {
+            warnings.push(`Section "${headingLine.trim()}" appears to be empty`);
+        }
+    }
+    // Warnings are soft limits and should not block generation.
+    const valid = errors.length === 0;
+    return {
+        valid,
+        warnings,
+        errors,
+        lineCount,
+        estimatedTokens,
+    };
+}
+//# sourceMappingURL=validators.js.map

package/dist/render/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../../src/render/validators.ts"],"names":[],"mappings":"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"}

package/dist/templates/base.mustache

@@ -0,0 +1,296 @@
+# AGENTS.md
+
+## Propósito del repositorio
+{{project_description}}
+
+## Tech stack
+{{#stacks}}
+- {{.}}
+{{/stacks}}
+
+## Comandos canónicos
+- Instalar dependencias: `{{commands.install}}`
+{{#has_dev}}
+- Ejecutar en local: `{{commands.dev}}`
+{{/has_dev}}
+{{#has_build}}
+- Build: `{{commands.build}}`
+{{/has_build}}
+{{#has_lint}}
+- Lint: `{{commands.lint}}`
+{{/has_lint}}
+{{#has_format}}
+- Format: `{{commands.format}}`
+{{/has_format}}
+{{#has_tests}}
+- Tests: `{{commands.test}}`
+{{/has_tests}}
+
+## Definition of Done
+Antes de considerar una tarea completa:
+{{#has_tests}}
+- [ ] `{{commands.test}}` pasa sin errores
+{{/has_tests}}
+{{#has_lint}}
+- [ ] `{{commands.lint}}` pasa sin errores
+{{/has_lint}}
+- [ ] No añadir dependencias nuevas sin confirmación
+- [ ] Documentar cambios en APIs públicas
+
+## Estilo y convenciones
+{{style_notes}}
+
+{{#has_tests}}
+## Testing guidelines
+{{testing_notes}}
+{{/has_tests}}
+
+{{#isStandardOrFull}}
+## How to work with AI agents
+
+### Task format
+- Start with a clear goal in one sentence.
+- State exact files that can be changed.
+- Include constraints (no new deps, no feature creep, deterministic output).
+- Define explicit acceptance criteria before implementation starts.
+
+### Requesting diffs and verification
+- Ask for a file-by-file change summary with reasons.
+- Request exact commands executed for validation.
+- Ask for test output summary (passed/failed and counts).
+- Require explicit mention of known risks or follow-up tasks.
+
+### Execution protocol
+1. Inspect relevant files first and summarize findings.
+2. Propose the smallest safe change.
+3. Implement incrementally and run tests after each meaningful step.
+4. Report what changed, what was validated, and what remains.
+
+## Expanded Definition of Done
+- [ ] Scope is fully implemented with no unrelated changes.
+- [ ] Output remains deterministic for same inputs.
+- [ ] No placeholders leak into generated markdown.
+- [ ] Error paths fail with clear messages.
+- [ ] Documentation and tests are updated when behavior changes.
+
+## Debug checklist
+- Reproduce with one deterministic command.
+- Capture expected vs actual behavior.
+- Confirm environment assumptions (Node version, package manager, cwd).
+- Check module resolution and path normalization first.
+- Validate generated content length and formatting.
+- Re-run minimal targeted tests before full suite.
+
+## Testing strategy
+- Prefer fast deterministic tests over broad flaky integration tests.
+- Keep fixtures small and representative.
+- Assert on stable output fragments, not volatile wording.
+{{#has_tests}}
+- Verify canonical test command: `{{commands.test}}`.
+- Add regression tests for every bug fix in rendering or detection.
+{{/has_tests}}
+{{^has_tests}}
+- If no test script exists, document manual verification steps.
+{{/has_tests}}
+
+{{#is_unknown_generic}}
+## Generic project execution playbook
+
+### Scope and boundaries
+- Prefer minimal, reversible changes over broad refactors.
+- Keep runtime and package-manager assumptions explicit.
+- Reuse existing folder conventions before introducing new structure.
+- Document any intentional tradeoff in the final handoff notes.
+- Keep public behavior stable unless the task explicitly requires change.
+
+### Baseline repository map
+- Confirm current source folders (`src`, `lib`, `app`, `scripts`) before editing.
+- Confirm test locations (`tests`, `__tests__`, `spec`) before adding files.
+- Confirm config entrypoints (`tsconfig`, linter, formatter, CI workflow) before updates.
+- Keep generated output deterministic across Windows and Linux runners.
+- Confirm output path and file ownership rules before writing AGENTS.md.
+
+### Change workflow
+1. Reproduce the issue with one deterministic command.
+2. Isolate the minimal layer to update (detect, render, validate, or cli).
+3. Add or update targeted tests before broad regression checks.
+4. Report changed files, commands run, and residual risks.
+
+### Validation when canonical scripts are missing
+- Run every available canonical command and capture output.
+{{^has_dev}}
+- If no dev script exists, describe the manual startup path in PR notes.
+{{/has_dev}}
+{{^has_build}}
+- If no build script exists, validate TypeScript or bundler config syntax directly.
+{{/has_build}}
+{{^has_tests}}
+- If no test script exists, add manual verification steps with deterministic inputs.
+{{/has_tests}}
+{{^has_lint}}
+- If no lint script exists, document style checks applied during review.
+{{/has_lint}}
+{{^has_format}}
+- If no format script exists, keep formatting changes isolated and minimal.
+{{/has_format}}
+
+### Generic PR checklist
+- [ ] Scope and files changed match the original request.
+- [ ] Validation evidence is attached for each claimed behavior change.
+- [ ] Backward compatibility assumptions are explicit.
+- [ ] Deterministic output is preserved for the same inputs.
+- [ ] Follow-up tasks are listed when work is intentionally deferred.
+
+### Handoff notes to include (generic repos)
+- What changed: list files and why.
+- How to validate: exact commands and expected outputs.
+- Risks: what could break and how to detect it fast.
+- Rollback: safest revert path if needed.
+
+### Updating scripts and docs safely
+- If a `package.json` script changes, update "Comandos canónicos".
+- For build/test/lint edits, include before/after command output.
+- Keep CI changes minimal and cross-platform.
+- Prefer reversible config updates scoped to the task.
+
+### Pre-merge sanity checks
+- Preview headings and checklist readability.
+- Re-run command examples on a clean clone.
+- Confirm profile output stays inside limits.
+- Confirm no placeholder content leaked.
+{{/is_unknown_generic}}
+
+## Do / Don't
+### Do
+- Do preserve existing behavior unless a change is requested.
+- Do keep commits minimal and reviewable.
+- Do fail fast on invalid user input.
+- Do prefer explicit conditions over hidden heuristics.
+
+### Don't
+- Don't invent commands that do not exist in package scripts.
+- Don't silently ignore validation errors.
+- Don't mix unrelated refactors with feature work.
+- Don't add dependencies unless strictly necessary.
+
+## Agent handoff template
+### Required fields
+- Goal: one sentence describing expected final state.
+- Scope: exact files or folders that can change.
+- Constraints: what must not change.
+- Validation: commands that prove the change.
+- Risks: known uncertainty or follow-up items.
+
+### Status update format
+- Completed: concrete items done.
+- In progress: current active step.
+- Next: immediate next action.
+- Blockers: missing info or external dependency.
+
+### Review checklist
+- [ ] File-level diff is easy to follow.
+- [ ] Tests cover changed behavior.
+- [ ] Output remains deterministic.
+- [ ] No hidden behavior changes.
+- [ ] Error handling is explicit.
+- [ ] Documentation reflects new behavior.
+
+### Escalation rules
+- Escalate when requirements conflict.
+- Escalate before adding dependencies.
+- Escalate before touching unrelated modules.
+- Escalate on ambiguous security implications.
+{{/isStandardOrFull}}
+
+{{#isFull}}
+## Advanced agent protocol
+
+### Change risk matrix
+- Low risk: copy updates, docs wording, isolated tests.
+- Medium risk: template condition changes, validation thresholds.
+- High risk: command detection logic, filesystem writes, CLI argument parsing.
+- For medium/high risk, require explicit before/after examples.
+
+### PR handoff checklist
+- Include rationale for each changed file.
+- Include verification commands and outcomes.
+- List backward-compatibility guarantees.
+- List residual risks and mitigations.
+
+### Failure triage flow
+1. Confirm failing command and exact error text.
+2. Isolate if failure is detection, rendering, or validation.
+3. Reproduce with fixture before touching production paths.
+4. Add regression coverage before finalizing fix.
+
+### CI hardening notes
+- Keep path handling platform neutral (`path.join`, no shell assumptions).
+- Keep tests independent from local machine state.
+- Avoid timing-sensitive assertions.
+- Keep generated artifacts reproducible across OSes.
+
+### Verification matrix
+| Layer | Check | Evidence |
+|---|---|---|
+| CLI | Arg parsing | command output |
+| Detection | scripts/framework | fixture result |
+| Rendering | profile sections | markdown preview |
+| Validation | limits/placeholders | unit tests |
+| E2E | dry-run command | test pass |
+
+### Rollback playbook
+1. Revert profile-specific template blocks first.
+2. Keep parser support only if backward compatible.
+3. Re-run compact profile tests and e2e.
+4. Re-introduce changes in smaller slices.
+
+### Communication protocol
+- Summarize assumptions before coding.
+- Report changed files immediately after edit step.
+- Report executed commands and outcomes.
+- Report unresolved risks before handoff.
+
+### Post-merge audit
+- Verify README examples still run as documented.
+- Verify SPEC and behavior remain aligned.
+- Verify CI pass on at least one Windows runner.
+- Verify default compact output remains unchanged.
+- Verify standard/full remain within configured limits.
+
+### Minimal failure report template
+- Command: exact failing command
+- Expected: what should happen
+- Actual: what happened
+- Suspected layer: detect/render/validate/cli
+- Reproduction fixture: path used
+
+### Final release gate
+- Confirm profile-specific limits pass validator.
+- Confirm placeholder checks remain strict.
+- Confirm default compact output is unchanged.
+- Confirm docs match implemented flags.
+- Confirm test suite is green in CI mode.
+- Confirm no unrelated files changed.
+- Confirm generated markdown still starts with # AGENTS.
+- Confirm profile ordering full > standard > compact.
+
+{{#is_unknown_generic}}
+## Generic full-profile operations guide
+
+### CI and branching policy
+- Require build, lint, and tests (or documented manual checks) before merge.
+- Keep branch names tied to one task or issue identifier.
+- Add rollback notes when behavior or templates change.
+
+### Extra verification for generic repos
+- Verify command paths for npm/yarn/pnpm when scripts are touched.
+- Capture before/after output for affected profile sections.
+- Include one failure-path test for validator or CLI behavior changes.
+{{/is_unknown_generic}}
+{{/isFull}}
+
+## Seguridad
+{{security_notes}}
+
+---
+*Generated by agents-md v0.1.0*

package/dist/templates/firebase.mustache

@@ -0,0 +1,236 @@
+# AGENTS.md
+
+## Propósito del repositorio
+{{project_description}}
+
+## Tech stack
+{{#stacks}}
+- {{.}}
+{{/stacks}}
+
+## Comandos canónicos
+- Instalar dependencias: `{{commands.install}}`
+{{#has_dev}}
+- Ejecutar emuladores locales: `{{commands.dev}}`
+{{/has_dev}}
+- Deploy a Firebase: `firebase deploy --only functions`
+{{#has_build}}
+- Build: `{{commands.build}}`
+{{/has_build}}
+{{#has_lint}}
+- Lint: `{{commands.lint}}`
+{{/has_lint}}
+{{#has_tests}}
+- Tests: `{{commands.test}}`
+{{/has_tests}}
+
+## Definition of Done
+Antes de considerar una tarea completa:
+{{#has_tests}}
+- [ ] `{{commands.test}}` pasa sin errores
+{{/has_tests}}
+{{#has_lint}}
+- [ ] `{{commands.lint}}` pasa sin errores
+{{/has_lint}}
+- [ ] Probado localmente con emuladores de Firebase
+- [ ] No añadir dependencias nuevas sin confirmación
+- [ ] Revisar quotas y límites de Firebase
+
+## Estilo y convenciones
+{{style_notes}}
+
+### Funciones Firebase
+- Funciones idempotentes (mismo input = mismo output)
+- Manejar cold starts: minimizar dependencias globales
+- Usar `onCall` para funciones HTTPS callable, `onRequest` para endpoints REST
+- Timeout configurado según caso de uso (default 60s, max 540s)
+
+## Environment variables
+- Variables de configuración en `.env` (local) y Firebase Config (producción)
+- Secrets en Google Secret Manager, accedidos via `functions.config()`
+- NO hardcodear API keys, tokens, o credenciales
+
+{{#has_tests}}
+## Testing guidelines
+{{testing_notes}}
+
+### Estrategia de testing
+- Unit tests para lógica de negocio (sin Firebase)
+- Integration tests con emuladores de Firebase
+- Mocking de Firebase Admin SDK cuando sea necesario
+{{/has_tests}}
+
+{{#isStandardOrFull}}
+## How to work with AI agents
+
+### Task format
+- Define objective, scope, and expected output up front.
+- Include affected Firebase resources (Functions, Firestore, Storage).
+- Keep changes minimal and deterministic.
+- Request explicit validation steps before closing the task.
+
+### Requesting diffs and validation
+- Ask for changed files and reason per file.
+- Ask for command log used for local validation.
+- Ask for test/emulator results with pass/fail summary.
+- Ask for security impact notes when touching auth or data paths.
+
+### Firebase delivery checklist
+- Confirm function triggers are correct and intentional.
+- Confirm retries/idempotency assumptions are explicit.
+- Confirm timeouts and resource usage are reasonable.
+- Confirm no secrets are embedded in source code.
+
+## Expanded Definition of Done
+- [ ] Scope complete with no unrelated refactors.
+- [ ] Emulator checks or equivalent local validation completed.
+- [ ] No placeholder values in generated markdown.
+- [ ] Docs and runbooks updated for behavior changes.
+- [ ] Backward compatibility confirmed for existing callers.
+
+## Debug checklist
+- Reproduce with emulator or deterministic fixture.
+- Verify environment variables and Firebase config source.
+- Check command detection and generated command section.
+- Validate output size and required sections by profile.
+- Re-run focused tests before full suite.
+
+## Testing strategy
+- Unit test pure business logic outside Firebase SDK wrappers.
+- Use emulator-backed integration tests for boundary behavior.
+- Keep assertions stable and deterministic.
+{{#has_tests}}
+- Keep command references aligned with `{{commands.test}}`.
+{{/has_tests}}
+
+## Do / Don't
+### Do
+- Do validate input and auth context on every entry point.
+- Do keep function side effects explicit.
+- Do document deploy and rollback expectations.
+- Do preserve default compact behavior.
+
+### Don't
+- Don't hardcode project ids, keys, or secrets.
+- Don't rely on implicit global state across invocations.
+- Don't skip validation on background triggers.
+- Don't bundle unrelated changes in one patch.
+
+## Agent handoff template
+### Required fields
+- Goal: one sentence describing expected final state.
+- Scope: exact files or folders that can change.
+- Constraints: what must not change.
+- Validation: commands that prove the change.
+- Risks: known uncertainty or follow-up items.
+
+### Status update format
+- Completed: concrete items done.
+- In progress: current active step.
+- Next: immediate next action.
+- Blockers: missing info or external dependency.
+
+### Review checklist
+- [ ] File-level diff is easy to follow.
+- [ ] Tests cover changed behavior.
+- [ ] Output remains deterministic.
+- [ ] No hidden behavior changes.
+- [ ] Error handling is explicit.
+- [ ] Documentation reflects new behavior.
+
+### Escalation rules
+- Escalate when requirements conflict.
+- Escalate before adding dependencies.
+- Escalate before touching unrelated modules.
+- Escalate on ambiguous security implications.
+{{/isStandardOrFull}}
+
+{{#isFull}}
+## Advanced agent protocol
+
+### Risk classification
+- Low: docs/template copy adjustments.
+- Medium: profile-dependent rendering and validation limits.
+- High: CLI parsing, deploy commands, and filesystem writes.
+- Medium/high changes require targeted regression tests.
+
+### PR handoff checklist
+- Provide before/after output for each affected profile.
+- Provide exact verification commands and outcomes.
+- Provide compatibility notes for existing workflows.
+- Provide residual risk and rollback guidance.
+
+### Failure triage flow
+1. Reproduce with fixture and explicit `--profile` flag.
+2. Isolate whether failure is detect/render/validate.
+3. Verify generated markdown includes required command set.
+4. Patch minimally and add regression coverage.
+
+### CI hardening notes
+- Keep tests OS-neutral for paths and execution.
+- Use non-shell process invocation in e2e tests.
+- Avoid timing-dependent assertions.
+- Keep fixtures small and deterministic.
+
+### Verification matrix
+| Layer | Check | Evidence |
+|---|---|---|
+| CLI | Arg parsing | command output |
+| Detection | scripts/framework | fixture result |
+| Rendering | profile sections | markdown preview |
+| Validation | limits/placeholders | unit tests |
+| E2E | dry-run command | test pass |
+
+### Rollback playbook
+1. Revert profile-specific template blocks first.
+2. Keep parser support only if backward compatible.
+3. Re-run compact profile tests and e2e.
+4. Re-introduce changes in smaller slices.
+
+### Communication protocol
+- Summarize assumptions before coding.
+- Report changed files immediately after edit step.
+- Report executed commands and outcomes.
+- Report unresolved risks before handoff.
+
+### Post-merge audit
+- Verify README examples still run as documented.
+- Verify SPEC and behavior remain aligned.
+- Verify CI pass on at least one Windows runner.
+- Verify default compact output remains unchanged.
+- Verify standard/full remain within configured limits.
+
+### Minimal failure report template
+- Command: exact failing command
+- Expected: what should happen
+- Actual: what happened
+- Suspected layer: detect/render/validate/cli
+- Reproduction fixture: path used
+
+### Final release gate
+- Confirm profile-specific limits pass validator.
+- Confirm placeholder checks remain strict.
+- Confirm default compact output is unchanged.
+- Confirm docs match implemented flags.
+- Confirm test suite is green in CI mode.
+- Confirm no unrelated files changed.
+- Confirm generated markdown still starts with # AGENTS.
+- Confirm profile ordering full > standard > compact.
+{{/isFull}}
+
+## Seguridad
+{{security_notes}}
+
+### Firebase-specific
+- Validar todos los inputs en funciones callable
+- Usar Firebase Auth para autenticación
+- Implementar Security Rules en Firestore/Storage
+- Nunca exponer Service Account keys en código
+
+## Deployment
+- Deploy staging: `firebase deploy --only functions --project staging`
+- Deploy producción: `firebase deploy --only functions --project production`
+- Rollback: `firebase functions:delete FUNCTION_NAME` + redeploy versión anterior
+
+---
+*Generated by agents-md v0.1.0*