forjajs 5.0.1 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (268) hide show
  1. package/CHANGELOG.md +114 -2
  2. package/README.md +40 -5
  3. package/README.pt-BR.md +42 -4
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/apps/cli/src/index.d.ts +0 -1
  50. package/dist/apps/cli/src/index.js +43 -32
  51. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  52. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  53. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  54. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  55. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  56. package/dist/apps/server/src/forja-nest.module.js +55 -0
  57. package/dist/apps/server/src/main.d.ts +21 -4
  58. package/dist/apps/server/src/main.js +79 -57
  59. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  60. package/dist/apps/server/src/task-planning-service.js +195 -0
  61. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  62. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  63. package/dist/bin/forja.js +3 -2
  64. package/dist/bin/init-project.js +1 -0
  65. package/dist/lib/agent-evals.d.ts +138 -0
  66. package/dist/lib/agent-evals.js +349 -0
  67. package/dist/lib/cli-output.js +14 -2
  68. package/dist/lib/code-context.d.ts +33 -5
  69. package/dist/lib/code-context.js +70 -5
  70. package/dist/lib/context-builder.d.ts +49 -4
  71. package/dist/lib/context-builder.js +114 -47
  72. package/dist/lib/core/coverage-gate.d.ts +59 -0
  73. package/dist/lib/core/coverage-gate.js +58 -0
  74. package/dist/lib/core/doc-graph.d.ts +38 -0
  75. package/dist/lib/core/doc-graph.js +83 -0
  76. package/dist/lib/core/health.js +286 -5
  77. package/dist/lib/core/journey.js +36 -0
  78. package/dist/lib/core/registry.js +81 -6
  79. package/dist/lib/docs-reference.d.ts +35 -0
  80. package/dist/lib/docs-reference.js +57 -0
  81. package/dist/lib/generators/memory-generator.d.ts +0 -11
  82. package/dist/lib/generators/memory-generator.js +5 -161
  83. package/dist/lib/generators/readme-generator.js +1 -1
  84. package/dist/lib/llm/json-output.d.ts +14 -0
  85. package/dist/lib/llm/json-output.js +77 -0
  86. package/dist/lib/project-wiring.d.ts +8 -0
  87. package/dist/lib/project-wiring.js +79 -3
  88. package/dist/lib/session-memory.d.ts +38 -0
  89. package/dist/lib/session-memory.js +206 -0
  90. package/dist/lib/spec-trace.d.ts +46 -0
  91. package/dist/lib/spec-trace.js +184 -0
  92. package/dist/lib/validators/structure-validator.js +0 -1
  93. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  94. package/dist/packages/adapter-nest/src/index.js +59 -1
  95. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  96. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  97. package/dist/packages/context/src/index.d.ts +2 -0
  98. package/dist/packages/context/src/index.js +36 -15
  99. package/dist/packages/contracts/src/index.d.ts +64 -0
  100. package/dist/packages/core/src/index.d.ts +9 -1
  101. package/dist/packages/core/src/index.js +28 -3
  102. package/dist/packages/graph/src/index.js +14 -5
  103. package/dist/packages/llm/src/index.js +12 -2
  104. package/dist/packages/mcp/src/index.d.ts +8 -0
  105. package/dist/packages/mcp/src/index.js +12 -1
  106. package/dist/packages/observability/src/index.d.ts +11 -0
  107. package/dist/packages/observability/src/index.js +3 -0
  108. package/dist/packages/orchestration/src/index.d.ts +15 -1
  109. package/dist/packages/orchestration/src/index.js +127 -21
  110. package/dist/packages/planner/src/index.d.ts +7 -1
  111. package/dist/packages/planner/src/index.js +67 -10
  112. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  113. package/dist/packages/planner/src/proposal-store.js +109 -0
  114. package/dist/packages/policy/src/index.d.ts +9 -16
  115. package/dist/packages/policy/src/index.js +114 -31
  116. package/dist/packages/runtime/src/index.d.ts +16 -2
  117. package/dist/packages/runtime/src/index.js +176 -61
  118. package/dist/scripts/build-smart-context.d.ts +2 -0
  119. package/dist/scripts/build-smart-context.js +12 -3
  120. package/dist/scripts/code-context.d.ts +3 -1
  121. package/dist/scripts/code-context.js +13 -3
  122. package/dist/scripts/coverage-gate.d.ts +2 -0
  123. package/dist/scripts/coverage-gate.js +101 -0
  124. package/dist/scripts/eval-agents.d.ts +11 -0
  125. package/dist/scripts/eval-agents.js +96 -0
  126. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  127. package/dist/scripts/gen-commands-doc.js +18 -0
  128. package/dist/scripts/hook-session-memory.d.ts +9 -0
  129. package/dist/scripts/hook-session-memory.js +20 -0
  130. package/dist/scripts/hook-session-start.js +34 -0
  131. package/dist/scripts/llm-fit.js +23 -1
  132. package/dist/scripts/spec-trace.d.ts +10 -0
  133. package/dist/scripts/spec-trace.js +73 -0
  134. package/dist/scripts/sync-universal-memory.js +69 -4
  135. package/dist/scripts/token-benchmark.d.ts +33 -1
  136. package/dist/scripts/token-benchmark.js +179 -5
  137. package/dist/scripts/token-economy.js +3 -1
  138. package/dist/scripts/tools-doctor.d.ts +16 -1
  139. package/dist/scripts/tools-doctor.js +58 -17
  140. package/docs/commands.md +155 -0
  141. package/docs/fluxo.md +11 -7
  142. package/docs/init-project.md +3 -1
  143. package/docs/llm-fit-loop.md +36 -0
  144. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  145. package/docs/produto/factsheet-marketing.md +7 -5
  146. package/docs/produto/roteiro-demo.md +14 -5
  147. package/docs/quick-reference.md +3 -3
  148. package/docs/token-optimization.md +10 -6
  149. package/memory/90-decisions/0088-templates-validados.md +3 -0
  150. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  151. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  152. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  153. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  154. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  155. package/package.json +4 -2
  156. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  157. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  158. package/specs/memoria-de-sessao/spec.md +48 -0
  159. package/specs/skills-do-projeto/plan.md +40 -0
  160. package/specs/skills-do-projeto/spec.md +63 -0
  161. package/specs/skills-do-projeto/tasks.md +27 -0
  162. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  163. package/specs/v6-core-consolidation/spec.md +70 -0
  164. package/specs/v6-docs-drift/spec.md +85 -0
  165. package/specs/v6-quality-gates/spec.md +99 -0
  166. package/specs/v6-token-economy/spec.md +84 -0
  167. package/templates/evals/agents/adr.json +25 -0
  168. package/templates/evals/agents/memoria.json +32 -0
  169. package/templates/evals/agents/proxima-acao.json +29 -0
  170. package/templates/evals/agents/spec-nova.json +26 -0
  171. package/templates/evals/agents/teste-do-criterio.json +29 -0
  172. package/templates/project/AGENTS.md +16 -0
  173. package/templates/project/CLAUDE.md +3 -2
  174. package/templates/project/agents/context-engineer.md +3 -0
  175. package/templates/project/agents/governance.md +3 -0
  176. package/templates/project/agents/marketing.md +3 -0
  177. package/templates/project/agents/orchestrator.md +3 -0
  178. package/templates/project/agents/product.md +3 -0
  179. package/templates/project/agents/sdd-architect.md +3 -0
  180. package/templates/project/skills/README.md +14 -0
  181. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  182. package/templates/project/skills/api-design/SKILL.md +77 -0
  183. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  184. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  185. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  186. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  187. package/templates/project/skills/commit-message/SKILL.md +143 -0
  188. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  189. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  190. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  191. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  192. package/templates/project/skills/event-storming/SKILL.md +95 -0
  193. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  194. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  195. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  196. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  197. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  198. package/templates/project/skills/observability/SKILL.md +93 -0
  199. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  200. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  201. package/templates/project/skills/pull-request/SKILL.md +101 -0
  202. package/templates/project/skills/query-performance/SKILL.md +83 -0
  203. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  204. package/templates/project/skills/release-notes/SKILL.md +87 -0
  205. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  206. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  207. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  208. package/templates/project/skills/testing/SKILL.md +109 -0
  209. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  210. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  211. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  212. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  213. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  214. package/templates/project/skills/web-performance/SKILL.md +72 -0
  215. package/boilerplates/02-saas-starter/.env.example +0 -25
  216. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  217. package/boilerplates/02-saas-starter/INFO.md +0 -252
  218. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  219. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  220. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  221. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  222. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  223. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  224. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  225. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  226. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  227. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  228. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  229. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  230. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  231. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  232. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  233. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  234. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  235. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  236. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  237. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  238. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  239. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  240. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  241. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  242. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  243. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  244. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  245. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  246. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  247. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  248. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  249. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  250. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  251. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  252. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  253. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  254. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  255. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  256. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  257. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  258. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  259. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  260. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  261. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  262. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  263. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  264. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  265. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  266. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  267. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  268. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: incident-postmortem
3
+ description: Use depois de um incidente em produção: escreve um postmortem sem culpados, com o impacto em números, uma linha do tempo em UTC, fatores contribuintes encontrados com os 5 Porquês, o que deu certo e ações com dono para prevenir, detectar e mitigar uma recorrência.
4
+ ---
5
+
6
+ # Postmortem de Incidente
7
+
8
+ Um postmortem transforma um incidente em aprendizado. Ele é **sem culpados**: as pessoas agiram de forma razoável com a informação e as ferramentas que tinham, então a pergunta é o que no sistema deixou a falha acontecer e se espalhar, não quem errou.
9
+
10
+ A saída padrão é um **documento de postmortem**. Ele é escrito a partir das evidências que o usuário fornece; o que não tem evidência é marcado como não confirmado.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: alertas, dashboards e logs de `observability`; transcrições do chat e do canal do incidente; histórico de deploys e mudanças (`git log`, execuções do CI); as pessoas envolvidas, por meio do usuário.
15
+ - Horários em UTC, com a fonte de cada entrada.
16
+ - Refira-se às pessoas pelo papel ("a pessoa de plantão"), não pelo nome.
17
+ - Idioma: o do usuário. Termos técnicos como o time os usa.
18
+ - Incógnitas vão para **Perguntas em aberto**. Nunca invente uma entrada na linha do tempo ou uma causa.
19
+
20
+ ## Linguagem sem culpados
21
+
22
+ - Descreva ações e decisões, e o contexto que as tornou razoáveis: "O deploy rodou sem canary porque o pipeline não tinha etapa de canary."
23
+ - Não "X esqueceu", "X deveria ter", "erro humano". Erro humano é um sintoma; pergunte o que tornou o erro fácil e o efeito dele grande.
24
+ - Contrafactuais ("se ao menos tivessem…") vão para as ações, não para a narrativa.
25
+
26
+ ## Processo
27
+
28
+ ### 1. Impacto
29
+ Em números: duração (início → mitigado → resolvido), usuários ou requisições afetados, taxa de erro, dados perdidos ou corrompidos, dinheiro, orçamento de erro do SLO consumido, implicações contratuais ou de LGPD (um incidente com dados pessoais pode exigir comunicação à ANPD: verifique com `lgpd-compliance`).
30
+
31
+ ### 2. Linha do tempo
32
+ Do primeiro gatilho (muitas vezes uma mudança dias antes) até a resolução. Marque os momentos-chave: **gatilho**, **detecção** (como: alerta, cliente, acaso), **início da resposta**, **mitigação**, **resolução**. Calcule o tempo até a detecção e o tempo até a mitigação.
33
+
34
+ ### 3. Fatores contribuintes
35
+ Sistemas complexos raramente falham por uma causa só. Liste os fatores que se combinaram: o gatilho, as condições latentes que permitiram que ele quebrasse as coisas, o que atrasou a detecção e o que desacelerou a mitigação. Para cada um, pergunte "por quê?" até chegar a algo que o time consiga mudar (5 Porquês), e pare aí.
36
+
37
+ ### 4. O que deu certo, o que deu errado, onde tivemos sorte
38
+ Sorte é um achado: ela marca uma defesa que ainda não existe.
39
+
40
+ ### 5. Ações
41
+ - Cada uma trata de um fator contribuinte e é de um destes tipos: **prevenir** (impedir o gatilho ou a condição latente), **detectar** (alertar mais cedo), **mitigar** (impacto menor, recuperação mais rápida).
42
+ - Específicas, com dono (um papel ou time), com ticket e com data. "Ter mais cuidado" não é uma ação.
43
+ - Prefira mudanças no sistema (testes, proteções, automação, alertas) a lembretes de processo.
44
+ - Poucas ações concluídas valem mais que uma lista longa que apodrece.
45
+
46
+ ## Formato
47
+
48
+ ```
49
+ # Postmortem: <título> — <data>
50
+ Status: <rascunho | revisado> · Severidade: <SEV-n> · Autores: <papéis>
51
+
52
+ ## Resumo
53
+ <3–4 frases: o que aconteceu, impacto, causa em resumo, estado atual>
54
+
55
+ ## Impacto
56
+ | Métrica | Valor |
57
+
58
+ ## Linha do tempo (UTC)
59
+ | Horário | Evento | Fonte |
60
+ Tempo até detectar: … · Tempo até mitigar: … · Tempo até resolver: …
61
+
62
+ ## Fatores contribuintes
63
+ ### <fator>
64
+ <descrição> — Cadeia de porquês: … → …
65
+
66
+ ## O que deu certo / errado / onde tivemos sorte
67
+
68
+ ## Ações
69
+ | # | Ação | Tipo (prevenir/detectar/mitigar) | Fator | Dono | Ticket | Prazo |
70
+
71
+ ## Perguntas em aberto
72
+ ```
73
+
74
+ ## Próximo
75
+
76
+ - `requirements-gathering`: `RNF-NN` novos a partir das ações.
77
+ - `testing`: um teste de regressão para o modo de falha.
78
+ - `observability`: alertas novos ou mudanças de SLO para as lacunas de detecção.
79
+ - `architecture-decision-record` quando a correção for uma mudança de design.
80
+ - `executive-writing` para um resumo curto à liderança ou aos clientes.
81
+
82
+ ## No Forja
83
+
84
+ No Forja, registre o incidente no grafo de engenharia com `forja incident:record --title "<título>" --description "<resumo>"`; incidentes parecidos aparecem em `forja incident:similar`. O documento do postmortem fica em `memory/60-runs/postmortems/<data>-<slug>.md`.
85
+
86
+ ## Evite
87
+
88
+ - Nomes e culpa, inclusive culpa implícita ("apesar do runbook…").
89
+ - Uma única causa raiz quando vários fatores se combinaram.
90
+ - Ações sem dono ou sem data.
91
+ - "Monitorar mais de perto" ou "ter mais cuidado" como ações.
92
+ - Linhas do tempo reconstruídas de memória, sem fontes.
93
+ - Publicar antes de as pessoas envolvidas revisarem.
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: lgpd-compliance
3
+ description: Use quando desenhar ou revisar um sistema, funcionalidade ou modelo de dados que trata dados pessoais sob a LGPD: classifica os dados, atribui bases legais, retenção e direitos dos titulares, e deriva os controles técnicos.
4
+ ---
5
+
6
+ # Conformidade com a LGPD
7
+
8
+ Aplica a LGPD (Lei nº 13.709/2018) a um sistema, funcionalidade ou modelo de domínio, pelo lado da engenharia: que dados existem, por que são tratados, com qual base legal, por quanto tempo, quem pode acessá-los e quais controles técnicos decorrem disso.
9
+
10
+ Isto é **conformidade desde a concepção** (privacy by design), não aconselhamento jurídico. Toda saída termina com os pontos que precisam ser validados pelo Encarregado ou pelo jurídico.
11
+
12
+ ## Convenções
13
+
14
+ - Termos jurídicos em pt-BR seguidos do en-US: Titular (Data Subject), Controlador (Controller), Operador (Processor), Encarregado (DPO), Tratamento (Processing), Base Legal (Legal Basis), Dado Pessoal Sensível (Sensitive Personal Data), Anonimização (Anonymization), Pseudonimização (Pseudonymization), RIPD (Data Protection Impact Assessment), ANPD (National Data Protection Authority).
15
+ - Cite os artigos da LGPD ao enunciar uma obrigação, para que possa ser verificada.
16
+ - Não invente bases legais nem prazos de retenção. Itens desconhecidos vão para **Perguntas em aberto**.
17
+ - As regulamentações da ANPD mudam. Quando um prazo ou procedimento depender de regulamento da ANPD, sinalize-o para verificação contra o texto vigente.
18
+
19
+ ## Princípio central
20
+
21
+ A conformidade começa pela **finalidade**. Todo dado pessoal precisa responder: para quê, com qual base, por quanto tempo. Um dado que não consegue responder é um dado que não deveria ser coletado (princípio da necessidade, Art. 6º, III).
22
+
23
+ ## Processo
24
+
25
+ ### 1. Inventariar os dados
26
+ Liste cada dado pessoal que o sistema coleta, deriva ou recebe de outros sistemas. Inclua os não óbvios: endereços IP, IDs de dispositivo, logs, geolocalização, campos de texto livre, uploads de arquivos, dados dentro de eventos e filas, backups.
27
+
28
+ ### 2. Classificar cada dado
29
+ | Classe | Definição | Artigo |
30
+ |---|---|---|
31
+ | Dado pessoal | Identifica ou pode identificar uma pessoa natural. | Art. 5º, I |
32
+ | Dado pessoal sensível | Origem racial ou étnica, convicção religiosa, opinião política, filiação a sindicato ou a organização de caráter religioso, filosófico ou político, dado referente à saúde ou à vida sexual, dado genético ou biométrico. | Art. 5º, II |
33
+ | Dados de crianças e adolescentes | Exigem tratamento no seu melhor interesse; dados de crianças seguem regras específicas. | Art. 14 |
34
+ | Dado anonimizado | Não pode ser reidentificado por meios razoáveis. Fora do escopo enquanto permanecer anônimo. | Art. 5º, III; Art. 12 |
35
+ | Dado pseudonimizado | Continua sendo dado pessoal: a reidentificação é possível com a chave mantida separada. | Art. 13, §4º |
36
+
37
+ ### 3. Ligar o tratamento à finalidade e à base legal
38
+ Para cada finalidade (não para cada campo), declare a finalidade em uma frase, os dados usados e a base legal.
39
+
40
+ - **Dados pessoais** (Art. 7º): consentimento; cumprimento de obrigação legal ou regulatória; administração pública; estudos por órgão de pesquisa; execução de contrato; exercício regular de direitos; proteção da vida; tutela da saúde por profissionais ou serviços de saúde; interesse legítimo; proteção do crédito.
41
+ - **Dados sensíveis** (Art. 11): lista mais restrita. Interesse legítimo, execução de contrato e proteção do crédito **não** estão disponíveis. Tutela da saúde, obrigação legal ou regulatória, proteção da vida, exercício regular de direitos e prevenção à fraude e à segurança do titular são os candidatos habituais.
42
+ - O **consentimento** precisa ser livre, informado, inequívoco e para uma finalidade determinada, e pode ser revogado (Art. 8º). Prefira outra base quando uma de fato se aplicar; um sistema construído sobre consentimento precisa suportar a revogação.
43
+ - O **interesse legítimo** exige um teste de balanceamento e só os dados estritamente necessários (Art. 10).
44
+
45
+ ### 4. Definir a retenção e o término do tratamento
46
+ Para cada finalidade: por quanto tempo o dado é mantido, o que dispara o término (Art. 15) e o que acontece depois: exclusão, anonimização ou conservação sob uma exceção do Art. 16 (por exemplo, obrigação legal). Um prazo legal de retenção precisa ser nomeado, não suposto.
47
+
48
+ ### 5. Atender aos direitos dos titulares (Art. 18)
49
+ Para cada direito, declare como o sistema o atende ou por que não se aplica:
50
+ confirmação da existência de tratamento; acesso; correção; anonimização, bloqueio ou eliminação de dados desnecessários ou excessivos; portabilidade; eliminação dos dados tratados com consentimento; informação sobre compartilhamento; informação sobre a possibilidade de não consentir; revogação do consentimento. E também a revisão de decisões automatizadas (Art. 20), quando o sistema as toma.
51
+
52
+ Consequência para a engenharia: os dados pessoais precisam ser localizáveis por titular em tabelas, arquivos, eventos e backups. Se não podem ser encontrados, não podem ser devolvidos nem excluídos.
53
+
54
+ ### 6. Mapear compartilhamentos e transferências
55
+ Liste cada destinatário: operadores (nuvem, e-mail, analytics, provedores de IA), outros controladores, órgãos públicos. Para transferências para fora do Brasil, identifique o mecanismo do Art. 33. Os operadores agem segundo as instruções do controlador (Art. 39).
56
+
57
+ ### 7. Derivar os controles técnicos (Art. 46)
58
+ Escolha de forma proporcional ao risco:
59
+ - **Minimização**: não colete o que não tem finalidade; evite campos de texto livre que atraem dados sensíveis.
60
+ - **Segregação**: dados sensíveis em tabelas ou schema próprios, com acesso restrito.
61
+ - **Criptografia**: em trânsito, sempre; em repouso para dados sensíveis (no nível da coluna ou da aplicação quando o nível do banco não for suficiente).
62
+ - **Pseudonimização**: para analytics, BI e réplicas que não precisam da identidade.
63
+ - **Controle de acesso**: privilégio mínimo, por papel e por finalidade; segurança por linha (row-level security) onde uma tabela atende vários contextos.
64
+ - **Trilha de auditoria**: registro somente de acréscimo de quem acessou ou alterou dados pessoais, quando e por quê. Na prática, exigido para responder a direitos e incidentes.
65
+ - **Logs e observabilidade**: nada de dados pessoais em logs, traces, labels de métricas ou mensagens de erro. Mascare por padrão.
66
+ - **Exclusão de verdade**: soft delete não é exclusão. Defina como a exclusão ou a anonimização chega a réplicas, caches, índices de busca, filas e backups.
67
+ - **Ambientes fora de produção**: nada de dados pessoais reais em desenvolvimento ou teste sem anonimização.
68
+
69
+ ### 8. Avaliar a necessidade de um relatório de impacto
70
+ Recomende um RIPD (Art. 38) quando o tratamento envolver dados sensíveis em escala, tratamento em larga escala, monitoramento sistemático, tecnologias novas, decisões automatizadas com efeito significativo, ou interesse legítimo como base para um tratamento de alto risco.
71
+
72
+ ### 9. Preparar-se para incidentes
73
+ Declare como um incidente de segurança seria detectado e dimensionado (quais titulares, quais dados). A comunicação à ANPD e aos titulares é obrigatória quando o incidente puder acarretar risco ou dano relevante (Art. 48); verifique o prazo no regulamento vigente da ANPD.
74
+
75
+ ## Formato de saída
76
+
77
+ ```
78
+ ## Inventário de dados
79
+ | Dado | Classe | Origem | Onde é armazenado | Finalidades |
80
+
81
+ ## Mapa de tratamento
82
+ | Finalidade | Dados | Base legal (artigo) | Retenção / gatilho de término | Destinatários |
83
+
84
+ ## Direitos dos titulares
85
+ | Direito | Como é atendido | Lacunas |
86
+
87
+ ## Controles técnicos
88
+ - <controle> — aplica-se a <dado/fluxo> — motivo
89
+
90
+ ## Relatório de impacto
91
+ <necessário / não necessário, e por quê>
92
+
93
+ ## Perguntas em aberto
94
+ - <base legal, prazo de retenção, contratos, transferências a validar com o Encarregado/jurídico>
95
+ ```
96
+
97
+ ## No Forja
98
+
99
+ No Forja, decisões de base legal, retenção e transferência viram ADR em `memory/90-decisions/`, e os requisitos derivados entram em §6 da spec (`specs/<slug>/spec.md`).
100
+
101
+ ## Evite
102
+
103
+ - Tratar o consentimento como base padrão para tudo.
104
+ - Supor que dados pseudonimizados estão fora da LGPD.
105
+ - Guardar dados "por via das dúvidas", sem finalidade nem prazo.
106
+ - Dados pessoais em logs, URLs, eventos de analytics ou fixtures de teste.
107
+ - Soft delete apresentado como exclusão.
108
+ - Apresentar conclusões como aconselhamento jurídico.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: llm-provider-routing
3
+ description: Use quando uma tarefa exige trocar de provedor ou modelo de LLM no Forja: seleciona, configura e verifica perfis, executa com contexto pela CLI, retoma sessões do Codex e valida as respostas com evidências.
4
+ ---
5
+
6
+ # Roteamento de LLMs
7
+
8
+ Siga o `AGENTS.md` do projeto. Para sintaxe e limites de cada comando, use `forja help <comando>`; não carregue catálogos de provedores sem necessidade.
9
+
10
+ 1. Identifique papel, tarefa, privacidade e restrições de custo/latência. Respeite a escolha autorizada pelo usuário; não troque modelo silenciosamente.
11
+ 2. Use `forja llm:profiles:init` e revise `.context/llm-profiles.json` no workspace. Configure um executável em `command`, argumentos em `commandArgs` e o identificador real do modelo. Não inclua credenciais nem comandos de shell.
12
+ 3. Execute `forja llm:probe <perfil>`. Registre versão e recursos detectados. Probe bem-sucedido não comprova autenticação nem acesso ao modelo.
13
+ 4. Consulte `forja llm:recommend --role <papel> --task <tipo>` como evidência auxiliar, sem tratar ranking como garantia de qualidade.
14
+ 5. Execute `forja llm:run --profile <perfil> --task <arquivo>`. Se necessário, use `--context <arquivo>` repetido. Confira o conteúdo antes de enviá-lo ao provedor.
15
+ 6. Para Codex compatível, use `--resume <session-id>` apenas com sessão conhecida no mesmo projeto/perfil. Use `--output-schema <arquivo>` e `--validation <manifest>` para formato e checks independentes. Revise os executáveis do manifest: eles rodam com permissões do Forja.
16
+ 7. Informe execução, validação, origem do uso de tokens e custo separadamente. Schema sozinho não comprova qualidade. Não afirme custo zero quando ele é desconhecido.
17
+
18
+ Se não houver adapter ou CLI compatível, explique a lacuna e configure um wrapper revisável somente dentro do escopo autorizado. Não invente suporte a API, MCP ou recursos de sessão. Não recomende um provedor por reputação sem evidência atual da tarefa.
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: observability
3
+ description: Use quando preparar um serviço ou funcionalidade para produção: deriva SLIs e SLOs dos requisitos não funcionais, planeja métricas, logs estruturados e traces, e define alertas baseados em sintomas, cada um com um esboço de runbook.
4
+ ---
5
+
6
+ # Observabilidade
7
+
8
+ Um sistema é observável quando você consegue responder a uma pergunta nova sobre o comportamento dele em produção sem publicar código novo. O objetivo não são dashboards: é saber que os usuários estão sofrendo antes que eles avisem, e descobrir o porquê rápido.
9
+
10
+ A saída padrão é um **plano de observabilidade**: SLOs, sinais e alertas. Escreva código de instrumentação só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: `RNF-NN` mensuráveis de `requirements-gathering`; endpoints de `api-design`; classificação de dados pessoais de `lgpd-compliance`; eventos de segurança de `threat-modeling`.
15
+ - Siga o código existente: a biblioteca de log, o backend de métricas e a configuração de tracing. Use [OpenTelemetry](https://opentelemetry.io/) e suas convenções semânticas como padrão quando não houver nada.
16
+ - Tráfego, metas ou escalas de plantão desconhecidos vão para **Perguntas em aberto**. Não invente metas de SLO; derive-as ou pergunte.
17
+
18
+ ## SLIs e SLOs
19
+
20
+ - Um **SLI** mede o que o usuário experimenta, como a razão entre eventos bons e eventos válidos: disponibilidade (respostas não-5xx / todas as respostas), latência (requisições abaixo de X ms / todas as requisições), atualidade, correção.
21
+ - Um **SLO** é a meta de um SLI numa janela: "99,5% dos `POST /orders` abaixo de 300 ms em 28 dias".
22
+ - Derive cada SLO de um `RNF-NN`. Quando o requisito não for mensurável, devolva-o para `requirements-gathering`.
23
+ - O **orçamento de erro** (100% − SLO) é o que os alertas e as decisões de release consomem.
24
+ - Poucos SLOs, nas jornadas de usuário que importam. Não um por endpoint.
25
+
26
+ ## Métricas
27
+
28
+ - **RED** para serviços guiados por requisições: Taxa (Rate), Erros, Duração (como histograma, nunca média).
29
+ - **USE** para recursos: Utilização, Saturação, Erros (pools, filas, CPU, memória).
30
+ - **Métricas de negócio** que dizem se a funcionalidade funciona: pedidos criados, pagamentos que falharam.
31
+ - Só labels com cardinalidade limitada: template da rota, método, classe do status. Nunca IDs de usuário, e-mails ou URLs cruas.
32
+
33
+ ## Logs
34
+
35
+ - Estruturados (JSON), um evento por linha, com `timestamp`, `level`, `message`, `service`, `trace_id` e os identificadores de domínio necessários para investigar (ID do pedido, não o nome do cliente).
36
+ - Os níveis significam algo: `error` exige ação; `warn` é inesperado mas tratado; `info` é um evento de negócio ou de ciclo de vida; `debug` fica desligado em produção.
37
+ - **Nada de dados pessoais, segredos ou tokens** nos logs (conforme `lgpd-compliance`). Quando for preciso um identificador, use um ID pseudônimo.
38
+ - Registre nas fronteiras e nas decisões, não em toda linha. Registre cada erro uma vez, onde ele é tratado.
39
+ - Os eventos de segurança de `threat-modeling` (falhas de autenticação, permissões negadas, acionamentos do limite de taxa) são registrados com o ator e o objeto.
40
+
41
+ ## Traces
42
+
43
+ - Propague o contexto em toda fronteira: HTTP, filas, jobs (W3C Trace Context).
44
+ - Spans para requisições de entrada, chamadas de saída, consultas ao banco e operações de fila, com atributos semânticos.
45
+ - Amostre por taxa, mas mantenha todos os traces de erro e os lentos quando o backend suportar amostragem na cauda (tail sampling).
46
+
47
+ ## Alertas
48
+
49
+ - Alerte sobre **sintomas** que os usuários sentem (taxa de consumo do SLO), não sobre causas (CPU em 80%).
50
+ - Use alertas de taxa de consumo com múltiplas janelas: consumo rápido aciona plantão (por exemplo, 2% do orçamento em 1 h), consumo lento abre um ticket (por exemplo, 10% em 3 dias).
51
+ - Todo acionamento de plantão é acionável, urgente e precisa de um humano. O resto é ticket ou dashboard.
52
+ - Todo alerta aponta para um esboço de runbook: o que significa, primeiras verificações, mitigação, escalonamento.
53
+
54
+ ## Formato
55
+
56
+ ```
57
+ ## SLOs
58
+ | SLO | SLI (bons / válidos) | Meta | Janela | Origem |
59
+ |---|---|---|---|---|
60
+ | Latência de criação de pedido | POST /orders < 300 ms / todos os POST /orders | 99,5% | 28d | RNF-03 |
61
+
62
+ ## Métricas
63
+ | Nome | Tipo | Labels | Finalidade |
64
+
65
+ ## Logs
66
+ <eventos por caso de uso: nível, mensagem, campos>
67
+
68
+ ## Traces
69
+ <fronteiras instrumentadas, amostragem>
70
+
71
+ ## Alertas
72
+ | Alerta | Condição | Severidade (plantão/ticket) | Runbook |
73
+
74
+ ## Esboços de runbook
75
+ ### <Alerta>
76
+ Significado: … Primeiras verificações: … Mitigação: … Escalonamento: …
77
+
78
+ ## Perguntas em aberto
79
+ ```
80
+
81
+ ## Próximo
82
+
83
+ - `testing`: verifique que os eventos de negócio críticos e os erros são registrados e medidos.
84
+ - `pull-request`: liste os sinais e alertas novos em "O quê".
85
+
86
+ ## Evite
87
+
88
+ - Alertar sobre toda métrica de causa.
89
+ - Médias para latência.
90
+ - Labels de alta cardinalidade.
91
+ - Dados pessoais, segredos ou corpos inteiros de requisição em logs ou atributos de span.
92
+ - SLOs em 100%, ou metas tiradas do nada.
93
+ - Dashboards que ninguém olha em vez de alertas que importam.
@@ -0,0 +1,130 @@
1
+ ---
2
+ name: product-evaluation
3
+ description: Use quando uma ideia de produto, startup, app, SaaS ou modelo de negócio precisa de uma avaliação crítica de viabilidade: põe à prova problema, mercado, escopo, concorrência, go-to-market e economia unitária, e devolve um veredito GO / WEAK GO / NO-GO com riscos e recomendações.
4
+ ---
5
+
6
+ # Avaliação de Produto
7
+
8
+ Põe um conceito de produto à prova contra a realidade do mercado antes que alguém gaste dinheiro para construí-lo. Entrada: um conceito (app, SaaS, plataforma, ferramenta ou serviço) com o que se sabe sobre público, funcionalidades, monetização e mercado. Saída: um veredito com a evidência por trás dele. Não é para dúvidas de implementação nem para redação de negócios em geral.
9
+
10
+ A avaliação não existe para encorajar. Existe para revelar os problemas enquanto ainda são baratos.
11
+
12
+ ## Convenções
13
+
14
+ - Termos em pt-BR seguidos do en-US: Proposta de Valor (Value Proposition), Adequação Produto-Mercado (Product-Market Fit), Custo de Aquisição de Cliente (Customer Acquisition Cost, CAC), Valor do Tempo de Vida do Cliente (Customer Lifetime Value, LTV), Custo de Troca (Switching Cost), Partida a Frio (Cold Start), Canal de Aquisição (Acquisition Channel).
15
+ - Toda afirmação traz sua natureza: **confirmada** (evidência fornecida ou encontrada), **suposta** (afirmada sem evidência), **desconhecida** (ninguém sabe ainda).
16
+ - Nomeie segmentos de forma concreta: não "PMEs", mas "uma agência de 3 pessoas que fatura 5+ clientes à mão, sem ninguém de operações".
17
+
18
+ ## Princípio central
19
+
20
+ O ceticismo é o padrão; o otimismo se conquista com evidência. Avalie o produto como descrito, não o pitch no melhor cenário: "vai viralizar" é uma suposição não validada, não uma estratégia de crescimento. Mas a falsa negatividade é tão prejudicial quanto a falsa positividade: se o produto é sólido, diga isso com clareza.
21
+
22
+ Seja específico. "Pode ser difícil de vender" é inútil; "a aquisição depende de SEO num espaço dominado por domínios de 10 anos" é útil.
23
+
24
+ ## Processo
25
+
26
+ ### 1. Problema e mercado
27
+ Interrogue o problema antes da solução.
28
+ - É real e recorrente, ou episódico e de nicho?
29
+ - Quem exatamente o tem?
30
+ - Qual o contorno atual? Se é uma planilha, por que ninguém construiu isso, ou por que as ferramentas existentes falharam?
31
+ - É analgésico (precisa resolver agora) ou vitamina (bom de ter)?
32
+ - O mercado cresce, está estável ou encolhe, e por quê? Há forças regulatórias, sazonais ou estruturais?
33
+
34
+ ### 2. Produto e escopo
35
+ Julgue as funcionalidades contra o problema e o usuário real, não contra o roadmap.
36
+ - A **ação de valor central**: a única coisa que o usuário precisa conseguir fazer para o produto ter entregado valor. Ela está priorizada?
37
+ - Quais funcionalidades a servem, e quais são especulativas ou exageradas antes de o núcleo ser validado?
38
+ - Que capacidade crítica um usuário sentiria falta de imediato?
39
+ - Superfície de risco técnico: APIs externas, qualidade dos dados, custo de infraestrutura em escala.
40
+ - O fluxo é realista para o usuário de verdade: atrito de onboarding, curva de aprendizado, comportamento inesperado?
41
+
42
+ ### 3. Concorrência e posicionamento
43
+ - Concorrentes diretos e indiretos, incluindo processos manuais, ferramentas estabelecidas e soluções adjacentes.
44
+ - Diferenciação estrutural (abordagem, modelo, execução), não "fazemos melhor".
45
+ - É defensável por 18 meses, ou será copiado assim que um player maior vir o nicho comprovado?
46
+ - Custos de troca criados. Sem eles, a retenção é uma luta constante.
47
+ - Risco de comoditização: está construído sobre uma camada que pode se tornar irrelevante (por exemplo, um invólucro fino sobre uma API de LLM que muda rápido)?
48
+
49
+ ### 4. Go-to-market e distribuição
50
+ Falha de distribuição mata mais produtos do que falha de produto.
51
+ - **Canal zero**: os 10 primeiros clientes, conquistados como, por quem?
52
+ - É executável pelos fundadores agora, ou exige recursos que eles não têm?
53
+ - Há um ciclo viral ou de indicação embutido, ou o crescimento vem só de mídia paga ou SEO?
54
+ - Ciclo de venda: autosserviço B2C vs. B2B com várias partes interessadas.
55
+ - Porteiros: lojas de apps, compras, jurídico, revisões de segurança de TI.
56
+ - A mensagem é específica o bastante para ressoar com alguém?
57
+
58
+ ### 5. Monetização e economia unitária
59
+ Verifique se o modelo é internamente consistente, não só plausível.
60
+ - O modelo de preço está alinhado a como os usuários percebem o valor?
61
+ - Há evidência de disposição a pagar (benchmarks, produtos análogos, pesquisa), ou é suposição?
62
+ - CAC:LTV com conversão e churn realistas, não otimistas.
63
+ - Vetores de custo em escala: computação, suporte, licenciamento de dados, compliance.
64
+ - Caminho até a economia unitária positiva, e em que escala?
65
+ - E se o principal canal de aquisição ficar 2× mais caro?
66
+
67
+ ### 6. Testes transversais
68
+ Aplique a todas as áreas acima:
69
+ - **Partida a frio**: o valor exige massa crítica? Como ela é formada?
70
+ - **Cadeias de dependência**: quais sistemas, APIs, plataformas ou regulações precisam se manter? O que quebra se mudarem?
71
+ - **Execução**: o time descrito consegue construir? O que está subestimado?
72
+ - **Momento**: cedo demais, agora, ou já passou do pico?
73
+ - **Uso real**: o que acontece quando os usuários fazem o inesperado?
74
+ - **Efeitos de segunda ordem**: o sucesso cria problemas novos (carga de suporte, custo de infraestrutura, atenção regulatória)?
75
+
76
+ ### 7. Veredito
77
+ - **GO**: o problema é real, existe um canal até os primeiros clientes, a conta fecha; os riscos restantes são conhecidos.
78
+ - **WEAK GO**: viável só se incógnitas específicas forem resolvidas antes; nomeie-as.
79
+ - **NO-GO**: uma falha estrutural que nenhum esforço razoável corrige.
80
+
81
+ Nomeie o único fator mais decisivo.
82
+
83
+ ### 8. Encaminhamento
84
+ Incógnitas a investigar → `requirements-elicitation`; escopo de um GO → `requirements-gathering`; riscos técnicos → `technical-spike`; dados pessoais → `lgpd-compliance`; veredito para as partes interessadas → `executive-writing`.
85
+
86
+ ## Formato de saída
87
+
88
+ ```
89
+ # Avaliação de produto: <produto>
90
+
91
+ ## Veredito
92
+ <GO | WEAK GO | NO-GO> — <um parágrafo nomeando o fator mais decisivo>
93
+
94
+ ## Pontos fortes
95
+ - <ponto forte específico> (ou: nenhum ponto forte claro)
96
+
97
+ ## Pontos fracos
98
+ 1. <problema estrutural ou de execução, do mais grave ao menos grave>
99
+
100
+ ## Riscos e incógnitas
101
+ - Conhecidos: <visíveis, gerenciáveis com esforço>
102
+ - Desconhecidos: <pontos cegos que exigem descoberta antes de seguir>
103
+ - Dependências externas: <fora do controle do time>
104
+
105
+ ## Recomendações
106
+ 1. <ação específica> — impacto: <...> — dificuldade/custo: <...>
107
+
108
+ ## Uso realista vs. idealizado
109
+ | Projetado para | Provavelmente usado para | Diferença |
110
+
111
+ ## Dependências e restrições
112
+ - Técnicas: ...
113
+ - Regulatórias: ...
114
+ - Momento de mercado: ...
115
+ - Time: ...
116
+ - Capital: ...
117
+
118
+ ## Encaminhamento
119
+ - <skill>: <o que vai para lá>
120
+ ```
121
+
122
+ ## Evite
123
+
124
+ - Consolo, rodeios ou enchimento.
125
+ - Feedback genérico que serviria para qualquer produto.
126
+ - Tratar as projeções do fundador ("viral", "todo mundo precisa disso") como evidência.
127
+ - Apresentar suposições como confirmadas.
128
+ - Negatividade sem razão estrutural; um produto sólido recebe um GO claro.
129
+ - Recomendações sem ordem, custo ou dificuldade.
130
+ - Desenhar a solução: telas, stack, arquitetura.
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: prompt-spec
3
+ description: Use quando passar trabalho de implementação para um agente de IA de código: transforma uma história ou requisito em prompts diretivos, prontos para colar, separados para backend e frontend, que exigem que o agente analise o código existente antes de mudar qualquer coisa e definem escopo, restrições e critérios de pronto.
4
+ ---
5
+
6
+ # Especificação de Prompt
7
+
8
+ Um agente de código faz o que o prompt torna fácil. Um prompt vago recebe uma implementação plausível que ignora os padrões do código, adiciona dependências e mexe em arquivos não relacionados. Um prompt diretivo declara o objetivo, obriga o agente a aprender o código antes, cerca o escopo e define "pronto" como comandos que passam.
9
+
10
+ A saída padrão é **um prompt por lado (backend, frontend), pronto para colar**, mais a ordem de execução. Esta skill escreve prompts; não executa o agente.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: uma história com critérios de aceite de `backlog-slicing`; o contrato de `api-design`; o modelo de `domain-modeling`; o próprio repositório (leia o README, o CLAUDE.md/AGENTS.md e a estrutura antes de escrever).
15
+ - Idioma do prompt: o do usuário, a menos que a documentação do código e os arquivos de agente estejam em outro.
16
+ - Frases imperativas e específicas. Sem gentilezas de enchimento, sem texto motivacional.
17
+ - Referencie caminhos, tipos e comandos reais do repositório. Leia-os antes; nunca invente um arquivo ou script.
18
+ - Um prompt = uma história ou fatia. Um prompt que precisa de "e também…" são dois prompts.
19
+
20
+ ## Por que separar backend e frontend
21
+
22
+ Eles têm bases de código ou pastas, convenções, testes e revisores diferentes. O **contrato da API é a costura**: o prompt de backend o implementa, o prompt de frontend o consome. Os dois citam o mesmo contrato, então podem rodar em paralelo ou em sequência sem divergir. Rode o backend primeiro quando o contrato é novo; em paralelo quando ele já existe.
23
+
24
+ ## Estrutura do prompt
25
+
26
+ Todo prompt tem estas seções, nesta ordem:
27
+
28
+ 1. **Objetivo**: uma ou duas frases, o resultado visível ao usuário. Referencie o ID da história.
29
+ 2. **Passo 0, analisar antes de implementar** (obrigatório): liste o que ler e o que relatar **antes de escrever código**:
30
+ - os arquivos e módulos que tratam de funcionalidades parecidas (nomeie-os);
31
+ - os padrões a copiar (tratamento de erro, validação, testes, nomes);
32
+ - os arquivos de agente (CLAUDE.md, AGENTS.md) e as configurações dos linters;
33
+ - um plano curto: arquivos a criar ou alterar, e por quê.
34
+ Instrua o agente a parar depois do relatório se algo contradisser o prompt.
35
+ 3. **Contexto**: as regras do domínio (`RN-NN`), o contrato (especificação do endpoint ou tipos), os ADRs relevantes. Cite-os; não parafraseie regras.
36
+ 4. **Requisitos**: os critérios de aceite em Dado/Quando/Então, literalmente.
37
+ 5. **Restrições**:
38
+ - seguir as convenções encontradas no passo 0;
39
+ - nenhuma dependência nova sem perguntar;
40
+ - os testes vão junto com a mudança (conforme `testing` / `ts-testing`);
41
+ - nada de refatorações, renomeações ou formatação não relacionadas;
42
+ - nenhuma mudança no contrato (o outro lado depende dele).
43
+ 6. **Fora do escopo**: o que não fazer, explicitamente (o outro lado, histórias futuras, migrações que são de outra pessoa).
44
+ 7. **Pronto quando**: comandos que precisam passar (`tsc --noEmit`, `npm test`, linters, build, como o repositório os define), e os critérios de aceite demonstrados.
45
+ 8. **Pare e pergunte se**: o contrato for impossível como escrito, uma regra for ambígua, a mudança precisar de uma migração ou de uma dependência nova, ou o passo 0 encontrar uma implementação existente.
46
+ 9. **Entregue**: um resumo dos arquivos alterados, como foi testado e uma mensagem de commit proposta (`commit-message`).
47
+
48
+ ## Formato
49
+
50
+ ````
51
+ ## Ordem de execução
52
+ <backend → frontend | paralelo>, porque <motivo>
53
+
54
+ ## Prompt de backend
55
+ ```text
56
+ <seções 1–9>
57
+ ```
58
+
59
+ ## Prompt de frontend
60
+ ```text
61
+ <seções 1–9>
62
+ ```
63
+ ````
64
+
65
+ Omita um lado quando a história só mexe no outro, e diga isso.
66
+
67
+ ## Próximo
68
+
69
+ - Depois que o agente rodar: `ts-code-review` (ou a revisão da linguagem), depois `commit-message` e `pull-request`.
70
+ - Se o passo 0 revelar uma questão de design: `architecture-decision-record` ou `technical-spike` antes de continuar.
71
+
72
+ ## No Forja
73
+
74
+ No Forja, além de colar o prompt, registre a entrega como handoff (ADR-0005), com os 7 campos: `forja hermes:handoff '<json>'`, mapeando *context* ← Contexto, *acceptance* ← Requisitos + Pronto quando, *constraints* ← Restrições + Fora do escopo, *return* ← Entregue. Quem recebe lista os seus com `forja agent:route list --open --mine` e fecha com `forja agent:route done <id>`.
75
+
76
+ ## Evite
77
+
78
+ - "Implemente a funcionalidade X" sem contexto.
79
+ - Pular o passo 0, ou deixar o agente codificar antes de relatar a análise.
80
+ - Um prompt só para backend e frontend juntos.
81
+ - Caminhos, scripts ou tipos que não existem no repositório.
82
+ - Deixar o agente mudar o contrato ou adicionar dependências em silêncio.
83
+ - "Pronto" sem comandos que o provem.
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: pull-request
3
+ description: Use quando abrir um pull request ou escrever a descrição dele: lê os commits e o diff do branch, escreve um título e um corpo com o porquê, o quê, como testar, riscos e rollback, e cria o PR só depois da aprovação.
4
+ ---
5
+
6
+ # Pull Request
7
+
8
+ Um pull request pede a um revisor que confie numa mudança. A descrição dá a ele o que o diff não consegue: por que a mudança existe, onde olhar, como verificá-la e o que acontece se der errado.
9
+
10
+ A saída padrão é um **título e um corpo propostos**. Crie o PR só depois que o usuário aprovar.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: os commits do branch (escritos com `commit-message`), os resultados de teste de `testing`, os IDs de requisito (`RF-NN`, `RN-NN`) de `requirements-gathering`, ADRs quando houve uma decisão.
15
+ - Idioma: o usado nos PRs ou commits recentes. Inglês quando não houver histórico.
16
+ - As regras do repositório prevalecem: `.github/pull_request_template.md`, `CONTRIBUTING.md`. Se houver um template, preencha-o em vez de usar o formato abaixo.
17
+
18
+ ## Reúna o contexto
19
+
20
+ Somente leitura, antes de redigir:
21
+
22
+ 1. `git branch --show-current` e o branch base (normalmente `main`).
23
+ 2. `git log <base>..HEAD --oneline`: a história do branch.
24
+ 3. `git diff <base>...HEAD --stat`, e depois o diff dos arquivos que carregam a mudança.
25
+ 4. `git status`: trabalho sem commit significa que o branch não está pronto. Diga isso; não abra o PR.
26
+ 5. Se o branch já foi enviado (`git rev-parse --abbrev-ref @{u}`).
27
+ 6. PRs mesclados recentes (`gh pr list --state merged -L 5`), para o tom e o estilo de título.
28
+
29
+ ## Título
30
+
31
+ - No formato Conventional Commits, como o assunto de um commit: `feat(reports): add CSV export`.
32
+ - Um branch com um commit só reutiliza o assunto desse commit.
33
+ - Um branch com vários commits recebe um assunto para o resultado inteiro, não para o último commit.
34
+ - `!` quando qualquer commit do branch for incompatível.
35
+
36
+ ## Regras do corpo
37
+
38
+ - **Porquê primeiro.** Uma ou duas frases sobre o problema. Ligue o ticket e os IDs de requisito.
39
+ - **O quê**, no nível que o revisor precisa: a abordagem e os arquivos que a carregam. Não uma lista arquivo por arquivo.
40
+ - **Como testar**: passos que o revisor consegue rodar, com comandos e resultados esperados. Declare o que foi rodado e o resultado. Nunca afirme que os testes passaram sem rodá-los.
41
+ - **Riscos e rollback**: o que pode quebrar, quem é afetado, como desfazer (revert, feature flag, rollback de migração de `data-migrations`).
42
+ - **Mudanças incompatíveis**: o que quebra e como os consumidores migram.
43
+ - **Capturas de tela ou gravações** quando a interface muda.
44
+ - **Orientação de revisão** para PRs grandes: por onde começar, o que pode ser lido por cima.
45
+ - Mantenha fácil de varrer com os olhos: títulos e marcadores curtos. Apague as seções vazias.
46
+
47
+ ## Tamanho
48
+
49
+ Um PR que não pode ser revisado de uma vez (cerca de 400 linhas alteradas de código real) deve ser dividido. Proponha a divisão por grupos de commits ou por fatia vertical de `backlog-slicing`. Arquivos gerados, lockfiles e movimentações não contam, mas mencione-os.
50
+
51
+ ## Formato
52
+
53
+ ```markdown
54
+ ## Por quê
55
+ <problema, em uma ou duas frases>. Refs: <ticket>, <RF-NN>
56
+
57
+ ## O quê
58
+ - <abordagem e mudança principal>
59
+ - <mudança secundária>
60
+
61
+ ## Como testar
62
+ 1. <comando ou passo> → <resultado esperado>
63
+
64
+ Rodado: <comando de teste> — <resultado>
65
+
66
+ ## Riscos e rollback
67
+ - Risco: <o que pode quebrar, para quem>
68
+ - Rollback: <revert / flag / passo de migração>
69
+
70
+ ## Mudanças incompatíveis
71
+ <o que quebra e como migrar>
72
+ ```
73
+
74
+ ## Fluxo
75
+
76
+ 1. Reúna o contexto.
77
+ 2. Redija título e corpo; sinalize uma divisão se o PR for grande demais.
78
+ 3. Mostre-os ao usuário.
79
+ 4. Com a aprovação: envie o branch se necessário (`git push -u origin <branch>`) e crie o PR com um heredoc:
80
+ ```sh
81
+ gh pr create --base <base> --title "<título>" --body-file - <<'EOF'
82
+ <corpo>
83
+ EOF
84
+ ```
85
+ 5. Mostre a URL do PR.
86
+
87
+ Crie como rascunho (`--draft`) quando o usuário disser que o trabalho não terminou. Nunca faça merge, force-push ou peça revisores, a menos que peçam.
88
+
89
+ ## Próximo
90
+
91
+ Depois do merge, `release-notes` transforma os commits mesclados numa versão e num changelog.
92
+
93
+ ## Evite
94
+
95
+ - Repetir a lista de commits como corpo.
96
+ - "Veja o código" ou uma descrição vazia.
97
+ - Afirmar que os testes passaram sem rodá-los.
98
+ - Esconder mudanças arriscadas num PR grande e não relacionado.
99
+ - Inventar IDs de ticket ou capturas de tela.
100
+ - Abrir o PR, enviar o branch ou pedir revisores sem aprovação.
101
+ - Ignorar o template de PR do repositório.