@jaimevalasek/aioson 1.7.0 → 1.8.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/CHANGELOG.md +60 -0
- package/README.md +153 -10
- package/docs/en/cli-reference.md +56 -1
- package/docs/en/i18n.md +18 -18
- package/docs/en/schemas/index.json +10 -0
- package/docs/en/schemas/parallel-assign.schema.json +9 -0
- package/docs/en/schemas/parallel-doctor.schema.json +36 -0
- package/docs/en/schemas/parallel-guard.schema.json +63 -0
- package/docs/en/schemas/parallel-merge.schema.json +84 -0
- package/docs/en/schemas/parallel-status.schema.json +91 -1
- package/docs/integrations/apps-publish-marketplace.md +94 -0
- package/docs/pt/README.md +9 -0
- package/docs/pt/agentes.md +324 -3
- package/docs/pt/clientes-ai.md +7 -3
- package/docs/pt/comandos-cli.md +160 -13
- package/docs/pt/compress-agents.md +304 -0
- package/docs/pt/design-docs-governance.md +59 -0
- package/docs/pt/feature-archive.md +191 -0
- package/docs/pt/genome-3.0-spec.md +115 -4
- package/docs/pt/genome-distribution.md +232 -0
- package/docs/pt/inicio-rapido.md +1 -0
- package/docs/pt/motor-hardening.md +492 -0
- package/docs/pt/runner-system.md +113 -0
- package/package.json +2 -1
- package/src/agent-manifests.js +66 -0
- package/src/agents.js +27 -7
- package/src/autonomy-policy.js +139 -0
- package/src/brain-query.js +161 -0
- package/src/cli.js +1377 -1099
- package/src/commands/agents.js +102 -7
- package/src/commands/artifact-validate.js +33 -4
- package/src/commands/auth.js +272 -0
- package/src/commands/brain-query.js +44 -0
- package/src/commands/briefing.js +344 -0
- package/src/commands/commit-prepare.js +547 -0
- package/src/commands/compress-agents.js +416 -0
- package/src/commands/context-health.js +4 -2
- package/src/commands/context-trim.js +17 -11
- package/src/commands/design-hybrid-options.js +3 -3
- package/src/commands/devlog-process.js +6 -4
- package/src/commands/dossier.js +423 -0
- package/src/commands/feature-archive.js +513 -0
- package/src/commands/feature-close.js +123 -18
- package/src/commands/gate-approve.js +198 -0
- package/src/commands/gate-check.js +24 -5
- package/src/commands/genome-doctor.js +166 -9
- package/src/commands/git-guard.js +170 -0
- package/src/commands/harness.js +121 -0
- package/src/commands/implementation-plan.js +47 -20
- package/src/commands/init.js +6 -2
- package/src/commands/install.js +6 -2
- package/src/commands/live.js +497 -56
- package/src/commands/locale-apply.js +9 -6
- package/src/commands/locale-diff.js +11 -112
- package/src/commands/mcp-doctor.js +2 -1
- package/src/commands/mcp-init.js +4 -10
- package/src/commands/memory.js +234 -0
- package/src/commands/parallel-assign.js +107 -27
- package/src/commands/parallel-doctor.js +416 -3
- package/src/commands/parallel-guard.js +241 -0
- package/src/commands/parallel-init.js +66 -4
- package/src/commands/parallel-merge.js +299 -0
- package/src/commands/parallel-status.js +147 -3
- package/src/commands/preflight.js +63 -4
- package/src/commands/qa-init.js +10 -5
- package/src/commands/revision.js +235 -0
- package/src/commands/scaffold-complete.js +188 -0
- package/src/commands/security-audit.js +275 -0
- package/src/commands/security-scan.js +376 -0
- package/src/commands/self-implement-loop.js +46 -2
- package/src/commands/setup-context.js +11 -10
- package/src/commands/squad-agent-create.js +51 -9
- package/src/commands/squad-investigate.js +53 -0
- package/src/commands/squad-plan.js +33 -1
- package/src/commands/squad-scaffold.js +4 -3
- package/src/commands/squad-score.js +71 -14
- package/src/commands/squad-status.js +22 -1
- package/src/commands/squad-validate.js +93 -2
- package/src/commands/store-genome.js +304 -0
- package/src/commands/store-skill.js +247 -0
- package/src/commands/store-squad.js +431 -0
- package/src/commands/store-system.js +392 -0
- package/src/commands/tool-capabilities.js +63 -0
- package/src/commands/update.js +3 -3
- package/src/commands/verify-gate.js +40 -0
- package/src/commands/workflow-execute.js +644 -155
- package/src/commands/workflow-harden.js +231 -0
- package/src/commands/workflow-heal.js +136 -0
- package/src/commands/workflow-next.js +460 -22
- package/src/commands/workflow-status.js +328 -138
- package/src/commands/workspace.js +144 -0
- package/src/constants.js +55 -75
- package/src/context-memory.js +133 -4
- package/src/context-writer.js +2 -1
- package/src/context.js +32 -2
- package/src/doctor.js +46 -6
- package/src/dossier/codemap-store.js +267 -0
- package/src/dossier/dossier-bootstrap.js +222 -0
- package/src/dossier/dossier-compact.js +159 -0
- package/src/dossier/lock.js +128 -0
- package/src/dossier/revision-store.js +313 -0
- package/src/dossier/schema.js +155 -0
- package/src/dossier/store.js +400 -0
- package/src/execution-gateway.js +3 -0
- package/src/friction-scanner.js +202 -0
- package/src/genome-schema.js +24 -1
- package/src/genomes.js +33 -0
- package/src/handoff-contract.js +363 -0
- package/src/handoff-validator.js +45 -0
- package/src/harness/circuit-breaker.js +135 -0
- package/src/i18n/messages/en.js +317 -22
- package/src/i18n/messages/es.js +259 -18
- package/src/i18n/messages/fr.js +260 -18
- package/src/i18n/messages/pt-BR.js +313 -22
- package/src/install-profile.js +0 -16
- package/src/installer.js +70 -6
- package/src/lib/git-commit-guard.js +691 -0
- package/src/lib/security/artifact-reader.js +167 -0
- package/src/lib/security/exit-codes.js +51 -0
- package/src/lib/security/findings-writer.js +176 -0
- package/src/lib/security/runtime-events.js +77 -0
- package/src/lib/security/secrets-regex.js +115 -0
- package/src/lib/store/security-scan.js +173 -0
- package/src/lib/terminal-checkbox.js +130 -0
- package/src/lib/tmux-launcher.js +163 -0
- package/src/lib/tool-capabilities.js +102 -0
- package/src/locales.js +12 -8
- package/src/parallel-workspace.js +756 -0
- package/src/parser.js +8 -1
- package/src/path-guard.js +47 -0
- package/src/preflight-engine.js +237 -26
- package/src/self-healing.js +142 -0
- package/src/session-handoff.js +111 -1
- package/src/squad/squad-scaffold.js +183 -19
- package/src/test-briefing.js +226 -0
- package/src/updater.js +1 -1
- package/src/utils.js +3 -0
- package/src/workflow-gates.js +185 -0
- package/template/.aioson/agents/analyst.md +76 -130
- package/template/.aioson/agents/architect.md +53 -86
- package/template/.aioson/agents/committer.md +161 -0
- package/template/.aioson/agents/copywriter.md +463 -0
- package/template/.aioson/agents/cypher.md +252 -0
- package/template/.aioson/agents/dev.md +112 -600
- package/template/.aioson/agents/deyvin.md +33 -235
- package/template/.aioson/agents/discover.md +235 -0
- package/template/.aioson/agents/discovery-design-doc.md +17 -252
- package/template/.aioson/agents/genome.md +76 -26
- package/template/.aioson/agents/manifests/analyst.manifest.json +26 -0
- package/template/.aioson/agents/manifests/architect.manifest.json +23 -0
- package/template/.aioson/agents/manifests/committer.manifest.json +23 -0
- package/template/.aioson/agents/manifests/dev.manifest.json +37 -0
- package/template/.aioson/agents/manifests/orchestrator.manifest.json +30 -0
- package/template/.aioson/agents/manifests/pentester.manifest.json +39 -0
- package/template/.aioson/agents/manifests/pm.manifest.json +26 -0
- package/template/.aioson/agents/manifests/product.manifest.json +23 -0
- package/template/.aioson/agents/manifests/qa.manifest.json +25 -0
- package/template/.aioson/agents/manifests/setup.manifest.json +20 -0
- package/template/.aioson/agents/manifests/ux-ui.manifest.json +24 -0
- package/template/.aioson/agents/neo.md +10 -8
- package/template/.aioson/agents/orache.md +2 -6
- package/template/.aioson/agents/orchestrator.md +81 -182
- package/template/.aioson/agents/pentester.md +235 -0
- package/template/.aioson/agents/pm.md +40 -104
- package/template/.aioson/agents/product.md +99 -344
- package/template/.aioson/agents/profiler-enricher.md +57 -6
- package/template/.aioson/agents/profiler-forge.md +17 -7
- package/template/.aioson/agents/profiler-researcher.md +29 -6
- package/template/.aioson/agents/qa.md +165 -410
- package/template/.aioson/agents/setup.md +52 -262
- package/template/.aioson/agents/sheldon.md +122 -754
- package/template/.aioson/agents/site-forge.md +111 -1583
- package/template/.aioson/agents/squad.md +139 -1820
- package/template/.aioson/agents/tester.md +10 -0
- package/template/.aioson/agents/ux-ui.md +103 -645
- package/template/.aioson/agents/validator.md +69 -0
- package/template/.aioson/brains/scripts/query.js +5 -1
- package/template/.aioson/config/autonomy-protocol.json +43 -0
- package/template/.aioson/config.md +43 -15
- package/template/.aioson/constitution.md +36 -33
- package/template/.aioson/context/design-doc.md +136 -0
- package/template/.aioson/context/project-map.md +57 -0
- package/template/.aioson/design-docs/code-reuse.md +48 -0
- package/template/.aioson/design-docs/componentization.md +47 -0
- package/template/.aioson/design-docs/file-size.md +52 -0
- package/template/.aioson/design-docs/folder-structure.md +51 -0
- package/template/.aioson/design-docs/naming.md +54 -0
- package/template/.aioson/docs/LAYERS.md +12 -2
- package/template/.aioson/docs/dev/execution-discipline.md +106 -0
- package/template/.aioson/docs/dev/stack-conventions.md +83 -0
- package/template/.aioson/docs/deyvin/continuity-recovery.md +57 -0
- package/template/.aioson/docs/deyvin/debugging-escalation.md +30 -0
- package/template/.aioson/docs/deyvin/pair-execution.md +44 -0
- package/template/.aioson/docs/deyvin/runtime-handoffs.md +36 -0
- package/template/.aioson/docs/product/conversation-playbook.md +116 -0
- package/template/.aioson/docs/product/prd-contract.md +107 -0
- package/template/.aioson/docs/product/quality-lens.md +57 -0
- package/template/.aioson/docs/product/research-loop.md +65 -0
- package/template/.aioson/docs/sheldon/enrichment-paths.md +134 -0
- package/template/.aioson/docs/sheldon/quality-lens.md +57 -0
- package/template/.aioson/docs/sheldon/research-loop.md +56 -0
- package/template/.aioson/docs/sheldon/web-intelligence.md +75 -0
- package/template/.aioson/docs/site-forge-build.md +195 -0
- package/template/.aioson/docs/site-forge-extraction.md +135 -0
- package/template/.aioson/docs/site-forge-qa.md +155 -0
- package/template/.aioson/docs/site-forge-recon.md +434 -0
- package/template/.aioson/docs/site-forge-transform.md +249 -0
- package/template/.aioson/docs/squad/content-output.md +91 -0
- package/template/.aioson/docs/squad/creation-flow.md +135 -0
- package/template/.aioson/docs/squad/domain-classification.md +117 -0
- package/template/.aioson/docs/squad/genome-bindings.md +47 -0
- package/template/.aioson/docs/squad/package-contract.md +234 -0
- package/template/.aioson/docs/squad/quality-lens.md +56 -0
- package/template/.aioson/docs/squad/research-loop.md +59 -0
- package/template/.aioson/docs/squad/session-operations.md +117 -0
- package/template/.aioson/docs/squad/workflow-quality.md +165 -0
- package/template/.aioson/docs/ux-ui/accessibility-audit.md +55 -0
- package/template/.aioson/docs/ux-ui/audit-mode.md +86 -0
- package/template/.aioson/docs/ux-ui/component-map.md +35 -0
- package/template/.aioson/docs/ux-ui/design-execution.md +111 -0
- package/template/.aioson/docs/ux-ui/design-gate.md +27 -0
- package/template/.aioson/docs/ux-ui/research-mode.md +39 -0
- package/template/.aioson/docs/ux-ui/site-delivery.md +156 -0
- package/template/.aioson/docs/ux-ui/token-contract.md +57 -0
- package/template/.aioson/genomes/copywriting.md +204 -0
- package/template/.aioson/genomes/copywriting.meta.json +48 -0
- package/template/.aioson/git-guard.json +11 -0
- package/template/.aioson/mcp/servers.md +0 -1
- package/template/.aioson/rules/agent-language-policy.md +93 -0
- package/template/.aioson/rules/aioson-context-boundary.md +63 -0
- package/template/.aioson/rules/canonical-path-contract.md +47 -0
- package/template/.aioson/rules/data-format-convention.md +24 -86
- package/template/.aioson/rules/disk-first-artifacts.md +44 -0
- package/template/.aioson/rules/output-brevity.md +44 -0
- package/template/.aioson/rules/prd-section-ownership.md +49 -0
- package/template/.aioson/rules/security-baseline.md +139 -0
- package/template/.aioson/rules/spec-level-ownership.md +61 -0
- package/template/.aioson/rules/squad-driver-pattern.md +81 -0
- package/template/.aioson/schemas/squad-blueprint.schema.json +24 -0
- package/template/.aioson/schemas/squad-manifest.schema.json +44 -0
- package/template/.aioson/skills/design/cognitive-core-ui/references/motion.md +2 -0
- package/template/.aioson/skills/marketing/references/anti-patterns.md +254 -0
- package/template/.aioson/skills/marketing/references/fascinations.md +192 -0
- package/template/.aioson/skills/marketing/references/five-acts.md +248 -0
- package/template/.aioson/skills/marketing/references/market-intelligence.md +198 -0
- package/template/.aioson/skills/marketing/references/offer-structure.md +203 -0
- package/template/.aioson/skills/marketing/references/one-belief.md +149 -0
- package/template/.aioson/skills/marketing/references/patterns.md +218 -0
- package/template/.aioson/skills/marketing/references/pms-research.md +193 -0
- package/template/.aioson/skills/marketing/vsl-craft.md +385 -0
- package/template/.aioson/skills/process/aioson-spec-driven/references/pm.md +30 -0
- package/template/.aioson/skills/process/secure-tdd/SKILL.md +97 -0
- package/template/.aioson/skills/process/secure-tdd/references/nextjs.md +81 -0
- package/template/.aioson/skills/process/secure-tdd/references/node-express.md +91 -0
- package/template/.aioson/skills/process/secure-tdd/references/planned-stacks.md +33 -0
- package/template/.aioson/skills/static/harness-validate/SKILL.md +46 -0
- package/template/.aioson/skills/static/landing-page-deploy.md +192 -0
- package/template/.aioson/skills/static/landing-page-forge.md +730 -0
- package/template/.aioson/skills/static/ui-ux-modern.md +1 -0
- package/template/.aioson/skills/static/web-research-cache.md +3 -0
- package/template/.aioson/tasks/squad-create.md +56 -7
- package/template/.aioson/tasks/squad-design.md +80 -2
- package/template/.aioson/tasks/squad-investigate.md +14 -1
- package/template/.aioson/templates/squads/digital-marketing-agency/template.json +96 -0
- package/template/.claude/commands/aioson/agent/committer.md +5 -0
- package/template/.claude/commands/aioson/agent/copywriter.md +5 -0
- package/template/.claude/commands/aioson/agent/cypher.md +5 -0
- package/template/.claude/commands/aioson/agent/pair.md +5 -0
- package/template/.claude/commands/aioson/agent/validator.md +5 -0
- package/template/.gemini/commands/aios-analyst.toml +6 -3
- package/template/.gemini/commands/aios-architect.toml +7 -6
- package/template/.gemini/commands/aios-committer.toml +7 -0
- package/template/.gemini/commands/aios-copywriter.toml +7 -0
- package/template/.gemini/commands/aios-cypher.toml +7 -0
- package/template/.gemini/commands/aios-dev.toml +8 -7
- package/template/.gemini/commands/aios-deyvin.toml +6 -5
- package/template/.gemini/commands/aios-discovery-design-doc.toml +6 -3
- package/template/.gemini/commands/aios-genome.toml +7 -0
- package/template/.gemini/commands/aios-neo.toml +5 -3
- package/template/.gemini/commands/aios-orache.toml +7 -0
- package/template/.gemini/commands/aios-orchestrator.toml +8 -7
- package/template/.gemini/commands/aios-pair.toml +6 -5
- package/template/.gemini/commands/aios-pm.toml +8 -7
- package/template/.gemini/commands/aios-product.toml +5 -3
- package/template/.gemini/commands/aios-qa.toml +6 -5
- package/template/.gemini/commands/aios-setup.toml +5 -2
- package/template/.gemini/commands/aios-sheldon.toml +7 -0
- package/template/.gemini/commands/aios-site-forge.toml +7 -0
- package/template/.gemini/commands/aios-squad.toml +7 -0
- package/template/.gemini/commands/aios-tester.toml +6 -5
- package/template/.gemini/commands/aios-ux-ui.toml +8 -7
- package/template/.gemini/commands/aios-validator.toml +7 -0
- package/template/AGENTS.md +12 -1
- package/template/CLAUDE.md +6 -1
- package/template/.aioson/locales/en/agents/analyst.md +0 -244
- package/template/.aioson/locales/en/agents/architect.md +0 -245
- package/template/.aioson/locales/en/agents/dev.md +0 -397
- package/template/.aioson/locales/en/agents/deyvin.md +0 -137
- package/template/.aioson/locales/en/agents/discovery-design-doc.md +0 -27
- package/template/.aioson/locales/en/agents/genome.md +0 -212
- package/template/.aioson/locales/en/agents/neo.md +0 -8
- package/template/.aioson/locales/en/agents/orache.md +0 -6
- package/template/.aioson/locales/en/agents/orchestrator.md +0 -189
- package/template/.aioson/locales/en/agents/pair.md +0 -5
- package/template/.aioson/locales/en/agents/pm.md +0 -84
- package/template/.aioson/locales/en/agents/product.md +0 -378
- package/template/.aioson/locales/en/agents/profiler-enricher.md +0 -5
- package/template/.aioson/locales/en/agents/profiler-forge.md +0 -5
- package/template/.aioson/locales/en/agents/profiler-researcher.md +0 -5
- package/template/.aioson/locales/en/agents/qa.md +0 -270
- package/template/.aioson/locales/en/agents/setup.md +0 -421
- package/template/.aioson/locales/en/agents/sheldon.md +0 -455
- package/template/.aioson/locales/en/agents/squad.md +0 -449
- package/template/.aioson/locales/en/agents/tester.md +0 -6
- package/template/.aioson/locales/en/agents/ux-ui.md +0 -668
- package/template/.aioson/locales/es/agents/analyst.md +0 -225
- package/template/.aioson/locales/es/agents/architect.md +0 -245
- package/template/.aioson/locales/es/agents/dev.md +0 -370
- package/template/.aioson/locales/es/agents/deyvin.md +0 -99
- package/template/.aioson/locales/es/agents/discovery-design-doc.md +0 -21
- package/template/.aioson/locales/es/agents/genome.md +0 -104
- package/template/.aioson/locales/es/agents/neo.md +0 -50
- package/template/.aioson/locales/es/agents/orache.md +0 -105
- package/template/.aioson/locales/es/agents/orchestrator.md +0 -194
- package/template/.aioson/locales/es/agents/pair.md +0 -7
- package/template/.aioson/locales/es/agents/pm.md +0 -90
- package/template/.aioson/locales/es/agents/product.md +0 -372
- package/template/.aioson/locales/es/agents/profiler-enricher.md +0 -7
- package/template/.aioson/locales/es/agents/profiler-forge.md +0 -7
- package/template/.aioson/locales/es/agents/profiler-researcher.md +0 -7
- package/template/.aioson/locales/es/agents/qa.md +0 -198
- package/template/.aioson/locales/es/agents/setup.md +0 -405
- package/template/.aioson/locales/es/agents/sheldon.md +0 -309
- package/template/.aioson/locales/es/agents/squad.md +0 -532
- package/template/.aioson/locales/es/agents/tester.md +0 -9
- package/template/.aioson/locales/es/agents/ux-ui.md +0 -212
- package/template/.aioson/locales/fr/agents/analyst.md +0 -225
- package/template/.aioson/locales/fr/agents/architect.md +0 -245
- package/template/.aioson/locales/fr/agents/dev.md +0 -370
- package/template/.aioson/locales/fr/agents/deyvin.md +0 -99
- package/template/.aioson/locales/fr/agents/discovery-design-doc.md +0 -21
- package/template/.aioson/locales/fr/agents/genome.md +0 -104
- package/template/.aioson/locales/fr/agents/neo.md +0 -50
- package/template/.aioson/locales/fr/agents/orache.md +0 -106
- package/template/.aioson/locales/fr/agents/orchestrator.md +0 -194
- package/template/.aioson/locales/fr/agents/pair.md +0 -7
- package/template/.aioson/locales/fr/agents/pm.md +0 -90
- package/template/.aioson/locales/fr/agents/product.md +0 -372
- package/template/.aioson/locales/fr/agents/profiler-enricher.md +0 -7
- package/template/.aioson/locales/fr/agents/profiler-forge.md +0 -7
- package/template/.aioson/locales/fr/agents/profiler-researcher.md +0 -7
- package/template/.aioson/locales/fr/agents/qa.md +0 -198
- package/template/.aioson/locales/fr/agents/setup.md +0 -405
- package/template/.aioson/locales/fr/agents/sheldon.md +0 -309
- package/template/.aioson/locales/fr/agents/squad.md +0 -532
- package/template/.aioson/locales/fr/agents/tester.md +0 -9
- package/template/.aioson/locales/fr/agents/ux-ui.md +0 -212
- package/template/.aioson/locales/pt-BR/agents/analyst.md +0 -319
- package/template/.aioson/locales/pt-BR/agents/architect.md +0 -284
- package/template/.aioson/locales/pt-BR/agents/dev.md +0 -483
- package/template/.aioson/locales/pt-BR/agents/deyvin.md +0 -184
- package/template/.aioson/locales/pt-BR/agents/discovery-design-doc.md +0 -198
- package/template/.aioson/locales/pt-BR/agents/genome.md +0 -297
- package/template/.aioson/locales/pt-BR/agents/neo.md +0 -208
- package/template/.aioson/locales/pt-BR/agents/orache.md +0 -137
- package/template/.aioson/locales/pt-BR/agents/orchestrator.md +0 -324
- package/template/.aioson/locales/pt-BR/agents/pair.md +0 -5
- package/template/.aioson/locales/pt-BR/agents/pm.md +0 -182
- package/template/.aioson/locales/pt-BR/agents/product.md +0 -466
- package/template/.aioson/locales/pt-BR/agents/profiler-enricher.md +0 -5
- package/template/.aioson/locales/pt-BR/agents/profiler-forge.md +0 -5
- package/template/.aioson/locales/pt-BR/agents/profiler-researcher.md +0 -5
- package/template/.aioson/locales/pt-BR/agents/qa.md +0 -300
- package/template/.aioson/locales/pt-BR/agents/setup.md +0 -533
- package/template/.aioson/locales/pt-BR/agents/sheldon.md +0 -323
- package/template/.aioson/locales/pt-BR/agents/squad.md +0 -1330
- package/template/.aioson/locales/pt-BR/agents/tester.md +0 -449
- package/template/.aioson/locales/pt-BR/agents/ux-ui.md +0 -669
- package/template/.aioson/skills/design-system/components/SKILL.md:Zone.Identifier +0 -0
- package/template/.aioson/skills/design-system/dashboards/SKILL.md:Zone.Identifier +0 -0
- package/template/.aioson/skills/design-system/foundations/SKILL.md:Zone.Identifier +0 -0
- package/template/.aioson/skills/design-system/motion/SKILL.md:Zone.Identifier +0 -0
- package/template/.aioson/skills/design-system/patterns/SKILL.md:Zone.Identifier +0 -0
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vsl-craft
|
|
3
|
+
description: Video Sales Letter production skill — script structure, hook formulas, retention techniques, testing methodology, and production specs. Loaded by @copywriter when Mode 5 (VSL) is active.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# VSL Craft — Video Sales Letter Production
|
|
7
|
+
|
|
8
|
+
## When to load this skill
|
|
9
|
+
|
|
10
|
+
- User requests a VSL script
|
|
11
|
+
- User requests a video sales page (page with embedded sales video)
|
|
12
|
+
- User requests an advertorial video
|
|
13
|
+
- @copywriter Mode 5 is activated
|
|
14
|
+
- Squad executor with VSL deliverable
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 1. What is a VSL?
|
|
19
|
+
|
|
20
|
+
A Video Sales Letter is a scripted video (typically 10-45 minutes) designed to convert cold traffic into buyers. It replaces the live salesperson with a pre-recorded, optimized sales presentation.
|
|
21
|
+
|
|
22
|
+
**Key differences from a written sales page:**
|
|
23
|
+
- The viewer can't scan — they must watch sequentially
|
|
24
|
+
- Retention is everything — if they leave at minute 3, the offer at minute 20 never gets seen
|
|
25
|
+
- Audio + visual = two channels to reinforce the message
|
|
26
|
+
- Pacing, pauses, and emotional tone are scripted, not left to chance
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 2. VSL formats
|
|
31
|
+
|
|
32
|
+
### 2.1 Traditional VSL (horizontal)
|
|
33
|
+
- 16:9 format, presenter or slides
|
|
34
|
+
- Duration: 15-45 minutes
|
|
35
|
+
- Best for: sophisticated offers, higher ticket (R$297+), cold traffic from YouTube/Facebook
|
|
36
|
+
- Production: can be "ugly" (slides only) or "cinematic" (B-roll, editing)
|
|
37
|
+
|
|
38
|
+
### 2.2 Vertical VSL (mobile-native)
|
|
39
|
+
- 9:16 format, looks like organic content
|
|
40
|
+
- Duration: 3-15 minutes
|
|
41
|
+
- Best for: TikTok/Reels traffic, lower ticket, younger audiences
|
|
42
|
+
- Production: phone-filmed, fast cuts, captions mandatory
|
|
43
|
+
|
|
44
|
+
### 2.3 Hybrid (advertorial + VSL)
|
|
45
|
+
- Written advertorial page with embedded video at the mechanism section
|
|
46
|
+
- The text does Act 1-2, the video does Act 3-5
|
|
47
|
+
- Best for: sophisticated audiences who want to read before watching
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## 3. The VSL script structure (5 Acts adapted for video)
|
|
52
|
+
|
|
53
|
+
### Act 1 — The Hook (0:00 to 0:30)
|
|
54
|
+
|
|
55
|
+
**Goal:** Stop the scroll and keep them watching for the next 30 seconds.
|
|
56
|
+
|
|
57
|
+
**The 3-second rule:** If the first 3 seconds aren't arresting, the viewer leaves.
|
|
58
|
+
|
|
59
|
+
**Hook formulas for VSL:**
|
|
60
|
+
|
|
61
|
+
**Formula 1: The Discovery Hook**
|
|
62
|
+
> "What you're about to see in the next [X] minutes could change the way you [desired outcome] forever. I'm going to show you [specific discovery] that [specific proof]."
|
|
63
|
+
|
|
64
|
+
**Formula 2: The Proof-First Hook**
|
|
65
|
+
> "[Name], [age], from [city], lost [specific result] in [specific time]. And she did it without [painful thing]. Today I'm going to show you exactly how — and why it works even if [objection]."
|
|
66
|
+
|
|
67
|
+
**Formula 3: The Paradox Hook**
|
|
68
|
+
> "Why do [specific group] [achieve result] while [audience group] [fail despite effort]? The answer has nothing to do with [obvious thing] — and everything to do with [curiosity element]."
|
|
69
|
+
|
|
70
|
+
**Formula 4: The Warning Hook**
|
|
71
|
+
> "If you're [doing common thing], stop immediately. A [authority/study] just revealed that [counterintuitive finding] — and it's costing you [consequence]. Stay with me for [time] and I'll show you [solution]."
|
|
72
|
+
|
|
73
|
+
**Formula 5: The Story Hook**
|
|
74
|
+
> "Last [day], [specific person] sent me this message: [screenshot/quote]. [X time] ago, they were [painful situation]. Today they [desired outcome]. This is their story — and it starts with [curiosity element]."
|
|
75
|
+
|
|
76
|
+
**Anti-pattern hooks:**
|
|
77
|
+
- "Hey everyone, welcome to my channel..." → Zero curiosity
|
|
78
|
+
- "In this video I'm going to talk about..." → Passive, no hook
|
|
79
|
+
- "So, I've been getting a lot of questions about..." → About you, not them
|
|
80
|
+
|
|
81
|
+
### Act 2 — The Background (0:30 to 3:00)
|
|
82
|
+
|
|
83
|
+
**Goal:** Build authority and emotional connection quickly.
|
|
84
|
+
|
|
85
|
+
**For expert-led VSL:**
|
|
86
|
+
> "[Credentials in one sentence]. But what matters more than my degrees is this: I've helped [specific number] of people [achieve result], and what I discovered along the way is the reason you're watching this video."
|
|
87
|
+
|
|
88
|
+
**For avatar transformation:**
|
|
89
|
+
> "I know what it's like to [specific pain]. [Time] ago, I was [painful situation — specific details]. I tried [what they've tried]. Nothing worked. Until [discovery moment]."
|
|
90
|
+
|
|
91
|
+
**Key rule:** Act 2 must be SHORT in a VSL. On a written page, you can have a long background section. On video, 1-2 minutes max. Get to the mechanism fast.
|
|
92
|
+
|
|
93
|
+
### Act 3 — The Mechanism (3:00 to 12:00)
|
|
94
|
+
|
|
95
|
+
**Goal:** Create the "Aha!" moment. This is where the One Belief is built.
|
|
96
|
+
|
|
97
|
+
**Structure:**
|
|
98
|
+
|
|
99
|
+
**Part A — Why nothing else worked (2-4 minutes)**
|
|
100
|
+
1. Name what they've tried (validate their experience)
|
|
101
|
+
2. Reveal the hidden reason it failed (the enemy — not them)
|
|
102
|
+
3. Use a visual metaphor or diagram to make the concept tangible
|
|
103
|
+
|
|
104
|
+
**Part B — How [Mechanism Name] works (3-5 minutes)**
|
|
105
|
+
1. Introduce the mechanism by name
|
|
106
|
+
2. Explain it at surface level (simple enough for a 12-year-old)
|
|
107
|
+
3. Show ONE proof point (study, case study, demonstration)
|
|
108
|
+
4. Use B-roll or diagrams to illustrate — never just talk over static slides for more than 30 seconds
|
|
109
|
+
|
|
110
|
+
**Retention techniques for Act 3:**
|
|
111
|
+
- **Pattern interrupt every 60-90 seconds:** Change the visual, show a diagram, cut to B-roll, display a quote
|
|
112
|
+
- **Open loops:** "In a moment I'll show you the third step — but first you need to understand why..."
|
|
113
|
+
- **Micro-fascinations:** Drop curiosity bullets throughout: "The ingredient I'm about to mention is in 90% of Brazilian homes but nobody knows it does THIS..."
|
|
114
|
+
- **Density escalation:** Each minute should be MORE interesting than the last, not less
|
|
115
|
+
|
|
116
|
+
### Act 4 — The Offer (12:00 to 18:00)
|
|
117
|
+
|
|
118
|
+
**Goal:** Transition from education to sale without breaking trust.
|
|
119
|
+
|
|
120
|
+
**The transition bridge:**
|
|
121
|
+
> "So now you understand WHY [mechanism] works and HOW it produces [result]. The question is: how do YOU implement it? That's exactly why I created [Product Name]."
|
|
122
|
+
|
|
123
|
+
**VSL-specific offer rules:**
|
|
124
|
+
- Never call it a "course" — use Protocol, System, Blueprint, Accelerator
|
|
125
|
+
- Show each component visually (mockup, icon, or slide)
|
|
126
|
+
- Read the fascinations with enthusiasm — pacing matters
|
|
127
|
+
- Pause after stating the price — let it sink in
|
|
128
|
+
- Show the guarantee prominently (text on screen + verbal)
|
|
129
|
+
|
|
130
|
+
**Reference:** `.aioson/skills/marketing/references/offer-structure.md`
|
|
131
|
+
|
|
132
|
+
### Act 5 — The Close (18:00 to 22:00)
|
|
133
|
+
|
|
134
|
+
**Goal:** Push the fence-sitters over the edge.
|
|
135
|
+
|
|
136
|
+
**The Two Paths technique (optimized for video):**
|
|
137
|
+
> "Right now, you're at a fork in the road.
|
|
138
|
+
> [Pause — 2 seconds]
|
|
139
|
+
> Path one: you close this video. You go back to [specific pain]. Tomorrow feels the same as today. Next month, same. Next year...
|
|
140
|
+
> [Pause — 3 seconds]
|
|
141
|
+
> Path two: you click the button below. You start [Product Name] today. In [timeframe], you [specific visualizable result].
|
|
142
|
+
> [Pause — 2 seconds]
|
|
143
|
+
> Which path makes more sense?"
|
|
144
|
+
|
|
145
|
+
**Recovery techniques (the "Kenyan Village" strategy):**
|
|
146
|
+
- **Pause thumbnail:** When the viewer pauses, a thumbnail appears with a hook to resume
|
|
147
|
+
- **Exit-intent popup:** On the page, when cursor moves to close — offer a discount or bonus
|
|
148
|
+
- **Post-VSL autoplay:** After the main VSL, play a shorter 3-minute "for those still deciding" video
|
|
149
|
+
- **SMS/email retargeting:** Capture email early (before VSL starts) and send follow-up sequence
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 4. VSL script format
|
|
154
|
+
|
|
155
|
+
When writing a VSL script, use this format:
|
|
156
|
+
|
|
157
|
+
```markdown
|
|
158
|
+
# VSL Script: [Product Name]
|
|
159
|
+
|
|
160
|
+
## Metadata
|
|
161
|
+
- Duration target: [X] minutes
|
|
162
|
+
- Format: Horizontal / Vertical
|
|
163
|
+
- Traffic temperature: Cold / Warm / Hot
|
|
164
|
+
- One Belief: "[New Opportunity] is the key to [Benefit] through [Mechanism]"
|
|
165
|
+
- Awareness level: [1-5]
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## ACT 1 — HOOK (0:00–0:30)
|
|
170
|
+
|
|
171
|
+
### VISUAL:
|
|
172
|
+
[What appears on screen]
|
|
173
|
+
|
|
174
|
+
### AUDIO:
|
|
175
|
+
[What is said — scripted word-for-word]
|
|
176
|
+
|
|
177
|
+
### NOTES:
|
|
178
|
+
[Production notes: B-roll, text overlay, music cue]
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## ACT 2 — BACKGROUND (0:30–3:00)
|
|
183
|
+
|
|
184
|
+
### VISUAL:
|
|
185
|
+
[Screen description]
|
|
186
|
+
|
|
187
|
+
### AUDIO:
|
|
188
|
+
[Script]
|
|
189
|
+
|
|
190
|
+
### NOTES:
|
|
191
|
+
[Production notes]
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## ACT 3 — MECHANISM (3:00–12:00)
|
|
196
|
+
|
|
197
|
+
### 3A — Why nothing else worked
|
|
198
|
+
|
|
199
|
+
#### VISUAL:
|
|
200
|
+
[Screen]
|
|
201
|
+
|
|
202
|
+
#### AUDIO:
|
|
203
|
+
[Script]
|
|
204
|
+
|
|
205
|
+
#### PATTERN INTERRUPT at [timestamp]:
|
|
206
|
+
[Visual change / diagram / B-roll description]
|
|
207
|
+
|
|
208
|
+
### 3B — How [Mechanism] works
|
|
209
|
+
|
|
210
|
+
#### VISUAL:
|
|
211
|
+
[Screen]
|
|
212
|
+
|
|
213
|
+
#### AUDIO:
|
|
214
|
+
[Script]
|
|
215
|
+
|
|
216
|
+
#### PROOF POINT:
|
|
217
|
+
[Study / case study / demonstration]
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## ACT 4 — OFFER (12:00–18:00)
|
|
222
|
+
|
|
223
|
+
### TRANSITION:
|
|
224
|
+
|
|
225
|
+
#### AUDIO:
|
|
226
|
+
[Bridge sentence]
|
|
227
|
+
|
|
228
|
+
### COMPONENT STACK:
|
|
229
|
+
|
|
230
|
+
#### VISUAL:
|
|
231
|
+
[Mockup / slide of each component]
|
|
232
|
+
|
|
233
|
+
#### AUDIO:
|
|
234
|
+
[Component name, benefit, value, fascination]
|
|
235
|
+
|
|
236
|
+
### PRICE REVEAL:
|
|
237
|
+
|
|
238
|
+
#### VISUAL:
|
|
239
|
+
[Anchoring → crossed out prices → final price]
|
|
240
|
+
|
|
241
|
+
#### AUDIO:
|
|
242
|
+
[Not paying X. Not even Y. Today: Z. Reason why.]
|
|
243
|
+
|
|
244
|
+
### GUARANTEE:
|
|
245
|
+
|
|
246
|
+
#### VISUAL:
|
|
247
|
+
[Guarantee badge / text on screen]
|
|
248
|
+
|
|
249
|
+
#### AUDIO:
|
|
250
|
+
[Full guarantee statement]
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## ACT 5 — CLOSE (18:00–22:00)
|
|
255
|
+
|
|
256
|
+
### TWO PATHS:
|
|
257
|
+
|
|
258
|
+
#### AUDIO:
|
|
259
|
+
[Path 1 → Path 2 → Which makes more sense?]
|
|
260
|
+
|
|
261
|
+
### FINAL CTA:
|
|
262
|
+
|
|
263
|
+
#### VISUAL:
|
|
264
|
+
[Button, URL, QR code on screen]
|
|
265
|
+
|
|
266
|
+
#### AUDIO:
|
|
267
|
+
[Click the button below / link in description]
|
|
268
|
+
|
|
269
|
+
### RECOVERY ELEMENTS:
|
|
270
|
+
- Pause thumbnail text: [text]
|
|
271
|
+
- Exit-intent offer: [discount/bonus]
|
|
272
|
+
- Post-VSL summary video: [Y/N]
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## 5. Testing methodology
|
|
278
|
+
|
|
279
|
+
### Phase 1 — Validate the thesis (before production)
|
|
280
|
+
Create an "ugly" VSL:
|
|
281
|
+
- White background, black text on slides
|
|
282
|
+
- Presenter reads from teleprompter (or text-to-speech for testing)
|
|
283
|
+
- No B-roll, no editing, no music
|
|
284
|
+
- Duration: 10-15 minutes (condensed version)
|
|
285
|
+
|
|
286
|
+
Run R$500-R$1,000 in cold traffic. Measure:
|
|
287
|
+
- **Hook retention:** % watching past 30 seconds (target: >50%)
|
|
288
|
+
- **Mechanism retention:** % watching past Act 3 (target: >25%)
|
|
289
|
+
- **Offer conversion:** % who reach offer AND click CTA (target: >2%)
|
|
290
|
+
|
|
291
|
+
If the ugly version converts → invest in production.
|
|
292
|
+
If it doesn't → rewrite the script before spending on video production.
|
|
293
|
+
|
|
294
|
+
### Phase 2 — Optimize the hook
|
|
295
|
+
Create 3-5 hook variations (first 30 seconds only).
|
|
296
|
+
Run equal traffic to each. The winning hook gets 2-3x more budget.
|
|
297
|
+
|
|
298
|
+
**Hook metrics:**
|
|
299
|
+
- 3-second retention rate
|
|
300
|
+
- 15-second retention rate
|
|
301
|
+
- 30-second retention rate
|
|
302
|
+
|
|
303
|
+
### Phase 3 — Scale with production
|
|
304
|
+
Once the script is validated:
|
|
305
|
+
- Add B-roll and visual elements
|
|
306
|
+
- Professional audio recording
|
|
307
|
+
- Add pattern interrupts and visual variety
|
|
308
|
+
- Consider vertical format for mobile-first traffic
|
|
309
|
+
|
|
310
|
+
---
|
|
311
|
+
|
|
312
|
+
## 6. VSL page structure
|
|
313
|
+
|
|
314
|
+
The page that hosts the VSL should be minimal:
|
|
315
|
+
|
|
316
|
+
```html
|
|
317
|
+
<!-- Above the fold — ONLY the video -->
|
|
318
|
+
<section class="vsl-hero">
|
|
319
|
+
<div class="video-container">
|
|
320
|
+
<!-- Video player (VTurb, Wistia, or custom) -->
|
|
321
|
+
<!-- CTA button appears ONLY after offer section plays -->
|
|
322
|
+
</div>
|
|
323
|
+
</section>
|
|
324
|
+
|
|
325
|
+
<!-- Below the fold — revealed after video plays past offer -->
|
|
326
|
+
<section class="vsl-offer">
|
|
327
|
+
<!-- Component stack (text version of what's in the video) -->
|
|
328
|
+
<!-- Guarantee -->
|
|
329
|
+
<!-- CTA button -->
|
|
330
|
+
<!-- FAQ -->
|
|
331
|
+
<!-- Testimonials -->
|
|
332
|
+
</section>
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
**Key rules:**
|
|
336
|
+
- **No navigation menu** — remove all escape routes
|
|
337
|
+
- **CTA button hidden until the offer section plays** — don't let them see the price before the mechanism
|
|
338
|
+
- **Video auto-plays on mute with captions** — most mobile traffic has sound off
|
|
339
|
+
- **Exit-intent popup** — "Wait! Before you go..." with a discount or bonus
|
|
340
|
+
- **Timer optional** — only if the offer has a real deadline
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## 7. Production specifications
|
|
345
|
+
|
|
346
|
+
### Audio
|
|
347
|
+
- Clear, professional recording (condenser mic, treated room)
|
|
348
|
+
- Pacing: 150-170 words per minute (conversational speed)
|
|
349
|
+
- Consider 1.1x-1.3x playback speed for higher engagement
|
|
350
|
+
- Music: subtle background only, never competing with voice
|
|
351
|
+
|
|
352
|
+
### Video
|
|
353
|
+
- Resolution: minimum 1080p
|
|
354
|
+
- B-roll: 2-3 second clips every 60-90 seconds in Act 3
|
|
355
|
+
- Text overlays: key claims and proof points on screen while spoken
|
|
356
|
+
- Captions: always (auto-generated + manually corrected)
|
|
357
|
+
|
|
358
|
+
### Hosting
|
|
359
|
+
- VTurb (Brazilian market — best heatmap and button reveal features)
|
|
360
|
+
- Wistia (international — CTA tools built in)
|
|
361
|
+
- Custom player (maximum control — no platform branding)
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## 8. Conditional reference loading
|
|
366
|
+
|
|
367
|
+
When writing a VSL script, the @copywriter agent should load:
|
|
368
|
+
|
|
369
|
+
| Phase | Load |
|
|
370
|
+
|---|---|
|
|
371
|
+
| Research | `pms-research.md` + `market-intelligence.md` |
|
|
372
|
+
| Script — hook | `one-belief.md` + `patterns.md` (headline formulas adapt to hooks) |
|
|
373
|
+
| Script — mechanism | `five-acts.md` (Acts 3 focus) |
|
|
374
|
+
| Script — offer | `offer-structure.md` + `fascinations.md` |
|
|
375
|
+
| Script — validation | `anti-patterns.md` |
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## 9. Output contract
|
|
380
|
+
|
|
381
|
+
VSL script saves to: `.aioson/context/vsl-script-{slug}.md`
|
|
382
|
+
VSL page spec saves to: `.aioson/context/vsl-page-{slug}.md` (if page design is needed)
|
|
383
|
+
|
|
384
|
+
If invoked from @ux-ui: return the page spec for visual implementation.
|
|
385
|
+
If invoked from a squad: save to the squad's output directory.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Spec-Driven Reference — @pm
|
|
2
|
+
|
|
3
|
+
> Router file. Do not duplicate logic from the generic references — load those directly.
|
|
4
|
+
|
|
5
|
+
## Which references to load for backlog and delivery planning
|
|
6
|
+
|
|
7
|
+
### Always load when this skill is active
|
|
8
|
+
|
|
9
|
+
- `approval-gates.md` — @pm owns Gate C; use it to know exactly what must be true before `phase_gates.plan` can be set to `approved` and before handing off to @dev or @orchestrator
|
|
10
|
+
- `classification-map.md` — use to calibrate sprint sizing and decide how many delivery phases are appropriate for MICRO/SMALL/MEDIUM
|
|
11
|
+
|
|
12
|
+
### Load when plan structure is ambiguous
|
|
13
|
+
|
|
14
|
+
- `artifact-map.md` — use to understand which artifacts @pm may read (prd, requirements, spec, architecture) vs. which it must not overwrite (@analyst's requirements, @architect's architecture)
|
|
15
|
+
- `maintenance-and-state.md` — use when retaking a sprint session or checking if a spec-{slug}.md checkpoint needs updating before continuing
|
|
16
|
+
|
|
17
|
+
### Do not load for @pm
|
|
18
|
+
|
|
19
|
+
- `hardening-lane.md` — @pm receives hardened input from @product and @analyst; if input is still vague, send it back upstream, do not harden it yourself
|
|
20
|
+
- `qa.md` — Gate D belongs to @qa, not @pm
|
|
21
|
+
|
|
22
|
+
## Behavioral notes for @pm under SDD
|
|
23
|
+
|
|
24
|
+
- @pm is the **Gate C owner** — the plan is not complete until `spec-{slug}.md` has `phase_gates.plan: approved` and `implementation-plan-{slug}.md` (if MEDIUM) has `status: approved`
|
|
25
|
+
- Gate C is **blocking in MEDIUM** — @dev and @orchestrator must not execute without Gate C passing
|
|
26
|
+
- Gate C is **informational in SMALL** — flag if the plan looks thin, but do not block
|
|
27
|
+
- Gate C is **skipped in MICRO** — @dev reads prd.md directly; @pm does not run for MICRO
|
|
28
|
+
- ACs produced by @pm must match or extend the ACs in `conformance-{slug}.yaml` when it exists — never contradict the analyst's behavioral contracts
|
|
29
|
+
- @pm adds delivery phases and prioritization; it does NOT rewrite Vision, Problem, Users, or Flows — those belong to @product
|
|
30
|
+
- At session end, always tell the user explicitly: "Gate C passed — activate [@orchestrator / @dev]" OR "Gate C blocked — [reason]"
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: secure-tdd
|
|
3
|
+
description: Process skill for adversarial TDD in security-sensitive features. Load after aioson-spec-driven when classification and attack surface justify it.
|
|
4
|
+
activation: |
|
|
5
|
+
You are now running the secure-tdd process. Confirm the feature classification and attack surface, load only the stack reference you need, write adversarial tests first, then implement production code.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Skill: secure-tdd
|
|
9
|
+
|
|
10
|
+
> Process skill. Adversarial tests before production code.
|
|
11
|
+
> Load this file first. Then load only the stack reference you need.
|
|
12
|
+
|
|
13
|
+
## When to use
|
|
14
|
+
|
|
15
|
+
Load this skill only after the normal feature workflow is already active.
|
|
16
|
+
|
|
17
|
+
- **MEDIUM:** load when the feature has auth, ownership, money, uploads, external URLs, secrets/credentials, or sensitive storage boundaries.
|
|
18
|
+
- **SMALL:** optional reduced mode for the same surfaces.
|
|
19
|
+
- **MICRO:** do not auto-load.
|
|
20
|
+
|
|
21
|
+
This skill complements `aioson-spec-driven`. It never replaces it.
|
|
22
|
+
|
|
23
|
+
## Loading order
|
|
24
|
+
|
|
25
|
+
1. Load `.aioson/skills/process/aioson-spec-driven/SKILL.md` first when the feature is spec-driven.
|
|
26
|
+
2. Read the current `requirements-{slug}.md`, `spec-{slug}.md`, and `architecture.md`.
|
|
27
|
+
3. Load `secure-tdd/SKILL.md`.
|
|
28
|
+
4. Load only one stack reference:
|
|
29
|
+
- `references/node-express.md`
|
|
30
|
+
- `references/nextjs.md`
|
|
31
|
+
5. If your stack is not covered by a full v1 reference, read `references/planned-stacks.md` for the minimal fallback.
|
|
32
|
+
|
|
33
|
+
## Goal
|
|
34
|
+
|
|
35
|
+
Make `@dev` write the security-sensitive tests first, before implementation, for the attack paths most likely to regress:
|
|
36
|
+
|
|
37
|
+
- auth bypass
|
|
38
|
+
- IDOR / ownership breaks
|
|
39
|
+
- race conditions / double-submit
|
|
40
|
+
- server-side validation gaps
|
|
41
|
+
- upload validation gaps
|
|
42
|
+
- unsafe external URL handling
|
|
43
|
+
- auth enumeration / rate limiting gaps
|
|
44
|
+
|
|
45
|
+
## Core rule
|
|
46
|
+
|
|
47
|
+
Frontend is never the authority.
|
|
48
|
+
Validation, authorization, limits, and sensitive state rules must be enforced server-side.
|
|
49
|
+
|
|
50
|
+
## Adversarial loop
|
|
51
|
+
|
|
52
|
+
1. Confirm the sensitive surface from requirements or the Attack Surface Map.
|
|
53
|
+
2. Map the surface to the relevant controls:
|
|
54
|
+
- `SEC-SBD-01` input limits
|
|
55
|
+
- `SEC-SBD-02` upload validation
|
|
56
|
+
- `SEC-SBD-03` ownership / IDOR / auth bypass
|
|
57
|
+
- `SEC-SBD-04` race condition / atomicity
|
|
58
|
+
- `SEC-SBD-06` external URL sanitization
|
|
59
|
+
- `SEC-SBD-08` auth enumeration / rate limiting
|
|
60
|
+
3. Write the minimum failing adversarial tests first.
|
|
61
|
+
4. Implement only enough production code to make those tests pass.
|
|
62
|
+
5. Re-run the tests immediately.
|
|
63
|
+
6. Record in `spec-{slug}.md` which attack classes are now covered.
|
|
64
|
+
|
|
65
|
+
`SEC-SBD-05` remains primarily tool-first via `security:scan`. Mention it in implementation decisions when relevant, but do not turn this skill into a secrets-scanning checklist.
|
|
66
|
+
|
|
67
|
+
## Output contract
|
|
68
|
+
|
|
69
|
+
When this skill is active, `@dev` should produce:
|
|
70
|
+
|
|
71
|
+
- at least one adversarial test per relevant sensitive surface
|
|
72
|
+
- a short note in `spec-{slug}.md` listing the covered attack classes
|
|
73
|
+
- no new product rules beyond what requirements and architecture already define
|
|
74
|
+
|
|
75
|
+
## Reduced mode for SMALL
|
|
76
|
+
|
|
77
|
+
For SMALL features:
|
|
78
|
+
|
|
79
|
+
- choose only the highest-risk surfaces
|
|
80
|
+
- prefer 1-2 adversarial tests over a full matrix
|
|
81
|
+
- do not block implementation just to expand the suite
|
|
82
|
+
|
|
83
|
+
## Non-goals
|
|
84
|
+
|
|
85
|
+
- do not invoke `@pentester`
|
|
86
|
+
- do not emit runtime events
|
|
87
|
+
- do not create CLI commands
|
|
88
|
+
- do not auto-generate large prompt libraries
|
|
89
|
+
- do not duplicate the baseline rule prose
|
|
90
|
+
|
|
91
|
+
## References available
|
|
92
|
+
|
|
93
|
+
| File | Load when |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `references/node-express.md` | Implementing Node / Express or service-style Node boundaries |
|
|
96
|
+
| `references/nextjs.md` | Implementing Next.js route handlers, server actions, or server-side validation |
|
|
97
|
+
| `references/planned-stacks.md` | The target stack is Laravel, Django, Rails, FastAPI, or another non-v1 stack |
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# secure-tdd reference: Next.js
|
|
2
|
+
|
|
3
|
+
Use this when the feature runs on Next.js route handlers, server actions, or server-side validation flows.
|
|
4
|
+
|
|
5
|
+
## Preferred runners
|
|
6
|
+
|
|
7
|
+
- Vitest
|
|
8
|
+
- Testing Library
|
|
9
|
+
- direct assertions on route handlers or server actions when available
|
|
10
|
+
|
|
11
|
+
## Write first
|
|
12
|
+
|
|
13
|
+
Start with failing tests that prove the server side rejects forged or cross-user behavior even if the UI looks correct.
|
|
14
|
+
|
|
15
|
+
Priority order:
|
|
16
|
+
1. auth bypass in route handlers or server actions
|
|
17
|
+
2. forged payload that bypasses UI constraints
|
|
18
|
+
3. IDOR / ownership checks on resource fetch or mutation
|
|
19
|
+
4. unsafe redirect / external URL handling
|
|
20
|
+
5. optimistic UI or double-submit that must not create duplicate critical state
|
|
21
|
+
|
|
22
|
+
## Minimum patterns
|
|
23
|
+
|
|
24
|
+
### Server-side validation independent of UI
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
it('rejects forged payloads on the server', async () => {
|
|
28
|
+
const res = await POST(new Request('http://test.local/api/resources', {
|
|
29
|
+
method: 'POST',
|
|
30
|
+
body: JSON.stringify({ title: 'x'.repeat(10000) })
|
|
31
|
+
}));
|
|
32
|
+
expect(res.status).toBe(422);
|
|
33
|
+
});
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Auth / ownership
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
it('blocks access to another users resource', async () => {
|
|
40
|
+
const res = await GET(
|
|
41
|
+
new Request('http://test.local/api/resources/foreign-id'),
|
|
42
|
+
{ params: { id: 'foreign-id' } }
|
|
43
|
+
);
|
|
44
|
+
expect([401, 403]).toContain(res.status);
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### External URL sanitization
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
it('rejects unsafe redirect targets', async () => {
|
|
52
|
+
const res = await POST(new Request('http://test.local/api/redirects', {
|
|
53
|
+
method: 'POST',
|
|
54
|
+
body: JSON.stringify({ target: 'javascript:alert(1)' })
|
|
55
|
+
}));
|
|
56
|
+
expect(res.status).toBe(422);
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
### Double-submit / optimistic UI distrust
|
|
61
|
+
|
|
62
|
+
Write a test proving the server allows only one critical mutation even if the client sends duplicates quickly.
|
|
63
|
+
|
|
64
|
+
## Control mapping
|
|
65
|
+
|
|
66
|
+
- `SEC-SBD-01`: route handler / action validation
|
|
67
|
+
- `SEC-SBD-03`: auth bypass / ownership
|
|
68
|
+
- `SEC-SBD-04`: duplicate mutation / optimistic UI distrust
|
|
69
|
+
- `SEC-SBD-06`: unsafe URL / redirect target
|
|
70
|
+
- `SEC-SBD-08`: auth messaging / rate-limiting when applicable
|
|
71
|
+
|
|
72
|
+
## Core reminder
|
|
73
|
+
|
|
74
|
+
UI affordances are not evidence.
|
|
75
|
+
Server actions, route handlers, and backend services must enforce the rule.
|
|
76
|
+
|
|
77
|
+
## Avoid
|
|
78
|
+
|
|
79
|
+
- testing only component rendering for a security-sensitive feature
|
|
80
|
+
- assuming hidden fields or disabled buttons are protection
|
|
81
|
+
- skipping server-action tests because the page already validates input
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# secure-tdd reference: Node / Express
|
|
2
|
+
|
|
3
|
+
Use this when the feature runs on Node.js request handlers, Express routes, or service boundaries tested with `node:test`.
|
|
4
|
+
|
|
5
|
+
## Preferred runners
|
|
6
|
+
|
|
7
|
+
- `node:test`
|
|
8
|
+
- `supertest` when the project already exposes an HTTP app
|
|
9
|
+
|
|
10
|
+
If the project is not HTTP-based, keep the same adversarial logic at the boundary-function level.
|
|
11
|
+
|
|
12
|
+
## Write first
|
|
13
|
+
|
|
14
|
+
Start with the smallest set of failing tests that proves the server rejects unsafe behavior.
|
|
15
|
+
|
|
16
|
+
Priority order:
|
|
17
|
+
1. auth bypass / missing auth
|
|
18
|
+
2. cross-user access (IDOR / ownership)
|
|
19
|
+
3. invalid payload beyond server-side limits
|
|
20
|
+
4. unsafe external URL or redirect target
|
|
21
|
+
5. concurrent mutation / race / double-submit when the feature mutates critical state
|
|
22
|
+
|
|
23
|
+
## Minimum patterns
|
|
24
|
+
|
|
25
|
+
### Auth bypass / ownership
|
|
26
|
+
|
|
27
|
+
Write a test that proves user A cannot read, mutate, or delete user B's resource.
|
|
28
|
+
|
|
29
|
+
```js
|
|
30
|
+
it('returns 403 when accessing another users resource', async () => {
|
|
31
|
+
const token = await loginAs(userA);
|
|
32
|
+
const res = await request(app)
|
|
33
|
+
.get(`/api/resources/${userBResource.id}`)
|
|
34
|
+
.set('Authorization', `Bearer ${token}`);
|
|
35
|
+
assert.equal(res.status, 403);
|
|
36
|
+
});
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Server-side validation
|
|
40
|
+
|
|
41
|
+
Write a test that sends a forged payload bigger or riskier than the UI should allow.
|
|
42
|
+
|
|
43
|
+
```js
|
|
44
|
+
it('rejects payloads that exceed server-side limits', async () => {
|
|
45
|
+
const res = await request(app)
|
|
46
|
+
.post('/api/resources')
|
|
47
|
+
.send({ title: 'x'.repeat(10_000) });
|
|
48
|
+
assert.equal(res.status, 422);
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### External URL sanitization
|
|
53
|
+
|
|
54
|
+
Write a test that sends an unsafe URL and expects rejection or strict allowlisting.
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
it('rejects unsafe external urls', async () => {
|
|
58
|
+
const res = await request(app)
|
|
59
|
+
.post('/api/redirects')
|
|
60
|
+
.send({ target: 'javascript:alert(1)' });
|
|
61
|
+
assert.equal(res.status, 422);
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Race condition / double-submit
|
|
66
|
+
|
|
67
|
+
When the feature changes critical state, write two competing calls and assert one of them is rejected or serialized correctly.
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
it('prevents duplicate critical mutations under concurrency', async () => {
|
|
71
|
+
const [a, b] = await Promise.all([
|
|
72
|
+
request(app).post('/api/refunds').send({ paymentId }),
|
|
73
|
+
request(app).post('/api/refunds').send({ paymentId })
|
|
74
|
+
]);
|
|
75
|
+
assert.equal([a.status, b.status].filter((s) => s === 200).length, 1);
|
|
76
|
+
});
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Control mapping
|
|
80
|
+
|
|
81
|
+
- `SEC-SBD-01`: payload size / field limit tests
|
|
82
|
+
- `SEC-SBD-03`: auth bypass and IDOR tests
|
|
83
|
+
- `SEC-SBD-04`: concurrency / double-submit tests
|
|
84
|
+
- `SEC-SBD-06`: external URL rejection / allowlist tests
|
|
85
|
+
- `SEC-SBD-08`: generic auth error / rate-limiting tests when applicable
|
|
86
|
+
|
|
87
|
+
## Avoid
|
|
88
|
+
|
|
89
|
+
- trusting frontend validation as evidence
|
|
90
|
+
- writing only happy-path tests for sensitive endpoints
|
|
91
|
+
- creating broad fixtures when a narrow reproduction is enough
|