verdicspec 0.0.0-stage → 0.2.2

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 (231) hide show
  1. package/.agents/agents/architect.md +12 -0
  2. package/.agents/agents/debugger.md +13 -0
  3. package/.agents/agents/explorer.md +16 -0
  4. package/.agents/agents/implementer.md +14 -0
  5. package/.agents/agents/observability-engineer.md +11 -0
  6. package/.agents/agents/planner.md +12 -0
  7. package/.agents/agents/pr-creator.md +11 -0
  8. package/.agents/agents/releaser.md +11 -0
  9. package/.agents/agents/reviewer.md +11 -0
  10. package/.agents/agents/security-reviewer.md +11 -0
  11. package/.agents/agents/specifier.md +14 -0
  12. package/.agents/agents/spike-engineer.md +12 -0
  13. package/.agents/agents/tester.md +12 -0
  14. package/.agents/agents/verifier.md +11 -0
  15. package/.agents/rules/agent-skill-routing.md +34 -0
  16. package/.agents/rules/verdicspec.md +7 -0
  17. package/.agents/skills/core/architecture/SKILL.md +16 -0
  18. package/.agents/skills/core/brownfield-analysis/SKILL.md +20 -0
  19. package/.agents/skills/core/debugging/SKILL.md +32 -0
  20. package/.agents/skills/core/planning/SKILL.md +18 -0
  21. package/.agents/skills/core/product-discovery/SKILL.md +20 -0
  22. package/.agents/skills/core/project-discovery/SKILL.md +32 -0
  23. package/.agents/skills/core/requirements/SKILL.md +13 -0
  24. package/.agents/skills/core/specification/SKILL.md +41 -0
  25. package/.agents/skills/core/spike/SKILL.md +30 -0
  26. package/.agents/skills/core/technology-discovery/SKILL.md +43 -0
  27. package/.agents/skills/practices/code-review/SKILL.md +21 -0
  28. package/.agents/skills/practices/data-migration/SKILL.md +14 -0
  29. package/.agents/skills/practices/observability/SKILL.md +28 -0
  30. package/.agents/skills/practices/observability/checklist.md +11 -0
  31. package/.agents/skills/practices/observability/references/dotnet.md +7 -0
  32. package/.agents/skills/practices/observability/references/java.md +9 -0
  33. package/.agents/skills/practices/observability/references/node.md +7 -0
  34. package/.agents/skills/practices/observability/references/python.md +7 -0
  35. package/.agents/skills/practices/observability/templates/logging-plan.md +16 -0
  36. package/.agents/skills/practices/observability/templates/metrics-plan.md +6 -0
  37. package/.agents/skills/practices/observability/templates/tracing-plan.md +14 -0
  38. package/.agents/skills/practices/pull-request/SKILL.md +17 -0
  39. package/.agents/skills/practices/release-readiness/SKILL.md +20 -0
  40. package/.agents/skills/practices/security/SKILL.md +11 -0
  41. package/.agents/skills/practices/testing/SKILL.md +37 -0
  42. package/.agents/skills/practices/verification/SKILL.md +15 -0
  43. package/.agents/skills/workflows/brownfield-change/SKILL.md +26 -0
  44. package/.agents/skills/workflows/bug-fix/SKILL.md +19 -0
  45. package/.agents/skills/workflows/feature-development/SKILL.md +35 -0
  46. package/.agents/skills/workflows/greenfield-product/SKILL.md +28 -0
  47. package/.claude/agents/architect.md +12 -0
  48. package/.claude/agents/debugger.md +13 -0
  49. package/.claude/agents/explorer.md +16 -0
  50. package/.claude/agents/implementer.md +14 -0
  51. package/.claude/agents/observability-engineer.md +11 -0
  52. package/.claude/agents/planner.md +12 -0
  53. package/.claude/agents/pr-creator.md +11 -0
  54. package/.claude/agents/releaser.md +11 -0
  55. package/.claude/agents/reviewer.md +11 -0
  56. package/.claude/agents/security-reviewer.md +11 -0
  57. package/.claude/agents/specifier.md +14 -0
  58. package/.claude/agents/spike-engineer.md +12 -0
  59. package/.claude/agents/tester.md +12 -0
  60. package/.claude/agents/verifier.md +11 -0
  61. package/.claude/rules/agent-skill-routing.md +34 -0
  62. package/.claude/rules/verdicspec.md +7 -0
  63. package/.claude/skills/core/architecture/SKILL.md +16 -0
  64. package/.claude/skills/core/brownfield-analysis/SKILL.md +20 -0
  65. package/.claude/skills/core/debugging/SKILL.md +32 -0
  66. package/.claude/skills/core/planning/SKILL.md +18 -0
  67. package/.claude/skills/core/product-discovery/SKILL.md +20 -0
  68. package/.claude/skills/core/project-discovery/SKILL.md +32 -0
  69. package/.claude/skills/core/requirements/SKILL.md +13 -0
  70. package/.claude/skills/core/specification/SKILL.md +41 -0
  71. package/.claude/skills/core/spike/SKILL.md +30 -0
  72. package/.claude/skills/core/technology-discovery/SKILL.md +43 -0
  73. package/.claude/skills/practices/code-review/SKILL.md +21 -0
  74. package/.claude/skills/practices/data-migration/SKILL.md +14 -0
  75. package/.claude/skills/practices/observability/SKILL.md +28 -0
  76. package/.claude/skills/practices/observability/checklist.md +11 -0
  77. package/.claude/skills/practices/observability/references/dotnet.md +7 -0
  78. package/.claude/skills/practices/observability/references/java.md +9 -0
  79. package/.claude/skills/practices/observability/references/node.md +7 -0
  80. package/.claude/skills/practices/observability/references/python.md +7 -0
  81. package/.claude/skills/practices/observability/templates/logging-plan.md +16 -0
  82. package/.claude/skills/practices/observability/templates/metrics-plan.md +6 -0
  83. package/.claude/skills/practices/observability/templates/tracing-plan.md +14 -0
  84. package/.claude/skills/practices/pull-request/SKILL.md +17 -0
  85. package/.claude/skills/practices/release-readiness/SKILL.md +20 -0
  86. package/.claude/skills/practices/security/SKILL.md +11 -0
  87. package/.claude/skills/practices/testing/SKILL.md +37 -0
  88. package/.claude/skills/practices/verification/SKILL.md +15 -0
  89. package/.claude/skills/workflows/brownfield-change/SKILL.md +26 -0
  90. package/.claude/skills/workflows/bug-fix/SKILL.md +19 -0
  91. package/.claude/skills/workflows/feature-development/SKILL.md +35 -0
  92. package/.claude/skills/workflows/greenfield-product/SKILL.md +28 -0
  93. package/.clinerules/verdicspec.md +6 -0
  94. package/.cursor/agents/architect.md +12 -0
  95. package/.cursor/agents/debugger.md +13 -0
  96. package/.cursor/agents/explorer.md +16 -0
  97. package/.cursor/agents/implementer.md +14 -0
  98. package/.cursor/agents/observability-engineer.md +11 -0
  99. package/.cursor/agents/planner.md +12 -0
  100. package/.cursor/agents/pr-creator.md +11 -0
  101. package/.cursor/agents/releaser.md +11 -0
  102. package/.cursor/agents/reviewer.md +11 -0
  103. package/.cursor/agents/security-reviewer.md +11 -0
  104. package/.cursor/agents/specifier.md +14 -0
  105. package/.cursor/agents/spike-engineer.md +12 -0
  106. package/.cursor/agents/tester.md +12 -0
  107. package/.cursor/agents/verifier.md +11 -0
  108. package/.cursor/rules/agent-skill-routing.mdc +34 -0
  109. package/.cursor/rules/verdicspec.mdc +7 -0
  110. package/.cursor/skills/core/architecture/SKILL.md +16 -0
  111. package/.cursor/skills/core/brownfield-analysis/SKILL.md +20 -0
  112. package/.cursor/skills/core/debugging/SKILL.md +32 -0
  113. package/.cursor/skills/core/planning/SKILL.md +18 -0
  114. package/.cursor/skills/core/product-discovery/SKILL.md +20 -0
  115. package/.cursor/skills/core/project-discovery/SKILL.md +32 -0
  116. package/.cursor/skills/core/requirements/SKILL.md +13 -0
  117. package/.cursor/skills/core/specification/SKILL.md +41 -0
  118. package/.cursor/skills/core/spike/SKILL.md +30 -0
  119. package/.cursor/skills/core/technology-discovery/SKILL.md +43 -0
  120. package/.cursor/skills/practices/code-review/SKILL.md +21 -0
  121. package/.cursor/skills/practices/data-migration/SKILL.md +14 -0
  122. package/.cursor/skills/practices/observability/SKILL.md +28 -0
  123. package/.cursor/skills/practices/observability/checklist.md +11 -0
  124. package/.cursor/skills/practices/observability/references/dotnet.md +7 -0
  125. package/.cursor/skills/practices/observability/references/java.md +9 -0
  126. package/.cursor/skills/practices/observability/references/node.md +7 -0
  127. package/.cursor/skills/practices/observability/references/python.md +7 -0
  128. package/.cursor/skills/practices/observability/templates/logging-plan.md +16 -0
  129. package/.cursor/skills/practices/observability/templates/metrics-plan.md +6 -0
  130. package/.cursor/skills/practices/observability/templates/tracing-plan.md +14 -0
  131. package/.cursor/skills/practices/pull-request/SKILL.md +17 -0
  132. package/.cursor/skills/practices/release-readiness/SKILL.md +20 -0
  133. package/.cursor/skills/practices/security/SKILL.md +11 -0
  134. package/.cursor/skills/practices/testing/SKILL.md +37 -0
  135. package/.cursor/skills/practices/verification/SKILL.md +15 -0
  136. package/.cursor/skills/workflows/brownfield-change/SKILL.md +26 -0
  137. package/.cursor/skills/workflows/bug-fix/SKILL.md +19 -0
  138. package/.cursor/skills/workflows/feature-development/SKILL.md +35 -0
  139. package/.cursor/skills/workflows/greenfield-product/SKILL.md +28 -0
  140. package/.github/copilot-instructions.md +6 -0
  141. package/.github/workflows/ci.yml +40 -0
  142. package/.github/workflows/publish.yml +32 -0
  143. package/.github/workflows/release.yml +104 -0
  144. package/.verdicspec/README.md +13 -0
  145. package/.verdicspec/config.json +17 -0
  146. package/AGENTS.md +60 -0
  147. package/CLAUDE.md +10 -0
  148. package/GEMINI.md +6 -0
  149. package/README.md +111 -2
  150. package/agents/architect.md +12 -0
  151. package/agents/debugger.md +13 -0
  152. package/agents/explorer.md +16 -0
  153. package/agents/implementer.md +14 -0
  154. package/agents/observability-engineer.md +11 -0
  155. package/agents/planner.md +12 -0
  156. package/agents/pr-creator.md +11 -0
  157. package/agents/releaser.md +11 -0
  158. package/agents/reviewer.md +11 -0
  159. package/agents/security-reviewer.md +11 -0
  160. package/agents/specifier.md +14 -0
  161. package/agents/spike-engineer.md +12 -0
  162. package/agents/tester.md +12 -0
  163. package/agents/verifier.md +11 -0
  164. package/bin/verdicspec.mjs +242 -0
  165. package/commands/debug.md +4 -0
  166. package/commands/discover.md +4 -0
  167. package/commands/map.md +4 -0
  168. package/commands/plan.md +4 -0
  169. package/commands/pr.md +4 -0
  170. package/commands/review.md +4 -0
  171. package/commands/specify.md +4 -0
  172. package/commands/spike.md +4 -0
  173. package/commands/verify.md +4 -0
  174. package/docs/artifact-contract.md +22 -0
  175. package/docs/commands.md +32 -0
  176. package/docs/method-overview.md +32 -0
  177. package/docs/npm-release.md +68 -0
  178. package/docs/portable-adapters.md +34 -0
  179. package/docs/project-modes.md +33 -0
  180. package/docs/specification-standard.md +25 -0
  181. package/docs/tool-support.md +24 -0
  182. package/docs/workflow.md +45 -0
  183. package/package.json +45 -4
  184. package/skills/core/architecture/SKILL.md +16 -0
  185. package/skills/core/brownfield-analysis/SKILL.md +20 -0
  186. package/skills/core/debugging/SKILL.md +32 -0
  187. package/skills/core/planning/SKILL.md +18 -0
  188. package/skills/core/product-discovery/SKILL.md +20 -0
  189. package/skills/core/project-discovery/SKILL.md +32 -0
  190. package/skills/core/requirements/SKILL.md +13 -0
  191. package/skills/core/specification/SKILL.md +41 -0
  192. package/skills/core/spike/SKILL.md +30 -0
  193. package/skills/core/technology-discovery/SKILL.md +43 -0
  194. package/skills/practices/code-review/SKILL.md +21 -0
  195. package/skills/practices/data-migration/SKILL.md +14 -0
  196. package/skills/practices/observability/SKILL.md +28 -0
  197. package/skills/practices/observability/checklist.md +11 -0
  198. package/skills/practices/observability/references/dotnet.md +7 -0
  199. package/skills/practices/observability/references/java.md +9 -0
  200. package/skills/practices/observability/references/node.md +7 -0
  201. package/skills/practices/observability/references/python.md +7 -0
  202. package/skills/practices/observability/templates/logging-plan.md +16 -0
  203. package/skills/practices/observability/templates/metrics-plan.md +6 -0
  204. package/skills/practices/observability/templates/tracing-plan.md +14 -0
  205. package/skills/practices/pull-request/SKILL.md +17 -0
  206. package/skills/practices/release-readiness/SKILL.md +20 -0
  207. package/skills/practices/security/SKILL.md +11 -0
  208. package/skills/practices/testing/SKILL.md +37 -0
  209. package/skills/practices/verification/SKILL.md +15 -0
  210. package/skills/workflows/brownfield-change/SKILL.md +26 -0
  211. package/skills/workflows/bug-fix/SKILL.md +19 -0
  212. package/skills/workflows/feature-development/SKILL.md +35 -0
  213. package/skills/workflows/greenfield-product/SKILL.md +28 -0
  214. package/technology-packs/dotnet/README.md +6 -0
  215. package/technology-packs/java/README.md +34 -0
  216. package/technology-packs/node/README.md +6 -0
  217. package/technology-packs/python/README.md +6 -0
  218. package/templates/brownfield-map.md +38 -0
  219. package/templates/bug-fix.md +36 -0
  220. package/templates/change-proposal.md +40 -0
  221. package/templates/decision-record.md +33 -0
  222. package/templates/feature-spec.md +50 -0
  223. package/templates/implementation-plan.md +33 -0
  224. package/templates/product-brief.md +41 -0
  225. package/templates/pull-request.md +27 -0
  226. package/templates/spike-report.md +36 -0
  227. package/templates/system-context.md +36 -0
  228. package/templates/technology-inventory.md +38 -0
  229. package/templates/test-plan.md +23 -0
  230. package/templates/threat-model.md +31 -0
  231. package/templates/verification-report.md +26 -0
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: spike-engineer
3
+ description: Responde pergunta tecnica com experimento limitado e evidencia. Use proativamente em incerteza tecnica.
4
+ ---
5
+
6
+ Voce e o agent `spike-engineer` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/core/spike/SKILL.md`.
10
+ 2. Limite tempo e escopo.
11
+ 3. Registre evidencia e conclusao.
12
+ 4. Nao trate spike como codigo de producao.
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: tester
3
+ description: Desenha e executa testes a partir do comportamento. Use proativamente em logica testavel e regressao.
4
+ ---
5
+
6
+ Voce e o agent `tester` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/practices/testing/SKILL.md`.
10
+ 2. Derive testes dos acceptance criteria.
11
+ 3. Execute e reporte evidencia real.
12
+ 4. Nao declare cobertura sem rodar.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: verifier
3
+ description: Gate final: mapeia acceptance criteria para evidencia executada. Use sempre antes de declarar pronto, commit ou PR.
4
+ ---
5
+
6
+ Voce e o agent `verifier` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/practices/verification/SKILL.md`.
10
+ 2. Separe evidenciado vs assumido.
11
+ 3. Nao declare sucesso sem evidencia fresca.
@@ -0,0 +1,34 @@
1
+ ---
2
+ description: Roteamento automatico de agents/skills Verdicspec — aplique sem o usuario pedir pelo nome
3
+ alwaysApply: true
4
+ ---
5
+
6
+ # Roteamento automatico (obrigatorio)
7
+
8
+ O usuario **nao precisa** dizer "use o agent X". Escolha pelo intent e carregue a skill canonica.
9
+
10
+ | Intent | Agent | Skill primaria |
11
+ |--------|-------|----------------|
12
+ | explorar / mapear / descobrir | `explorer` | `skills/core/project-discovery` |
13
+ | especificar feature / comportamento | `specifier` | `skills/core/specification` |
14
+ | planejar tasks | `planner` | `skills/core/planning` |
15
+ | arquitetura / trade-offs | `architect` | `skills/core/architecture` |
16
+ | bug / erro / regressao | `debugger` | `skills/core/debugging` |
17
+ | spike / incerteza tecnica | `spike-engineer` | `skills/core/spike` |
18
+ | implementar apos aprovacao | `implementer` | `skills/workflows/feature-development` |
19
+ | testes | `tester` | `skills/practices/testing` |
20
+ | pronto? / gate final | `verifier` | `skills/practices/verification` |
21
+ | seguranca | `security-reviewer` | `skills/practices/security` |
22
+ | logs / metricas | `observability-engineer` | `skills/practices/observability` |
23
+ | review de codigo | `reviewer` | `skills/practices/code-review` |
24
+ | criar PR | `pr-creator` | `skills/practices/pull-request` |
25
+ | release | `releaser` | `skills/practices/release-readiness` |
26
+
27
+ ## Gates
28
+
29
+ 1. Stack desconhecida → `technology-discovery` antes.
30
+ 2. Feature media/grande → specify → aprovacao → plan → implement.
31
+ 3. Bug → causa raiz antes de patch.
32
+ 4. Antes de pronto/commit/PR → `verifier`.
33
+ 5. Nao modernize stack/padrao sem pedido explicito.
34
+ 6. Nao declare evidencia que nao foi executada.
@@ -0,0 +1,7 @@
1
+ ---
2
+ description: Apply the Verdicspec to software engineering work in this repository.
3
+ alwaysApply: true
4
+ ---
5
+
6
+ Read `AGENTS.md` before working. Use the smallest applicable skill from `skills/`, and use the relevant technology pack from `technology-packs/`. Keep requirements, implementation, and verification evidence explicit. Do not claim validation that was not executed.
7
+
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: architecture
3
+ description: Make proportionate architecture decisions grounded in the existing codebase and constraints.
4
+ ---
5
+
6
+ # Architecture
7
+
8
+ 1. Determine project mode and map the current boundaries, dependencies, data flow, and extension points.
9
+ 2. Find existing patterns before introducing a new one.
10
+ 3. State constraints, alternatives, trade-offs, and rejected options.
11
+ 4. Prefer the smallest design that preserves testability, operability, and future change.
12
+ 5. Consider security, privacy, accessibility, reliability, performance, operability, and cost as architecture concerns.
13
+ 6. Record decisions that affect public interfaces, persistence, deployment, security, or ownership.
14
+
15
+ Do not create abstractions only to avoid a small amount of repetition.
16
+
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: brownfield-analysis
3
+ description: Analyze an existing codebase and running system to identify behavior, boundaries, invariants, risks, and safe change seams.
4
+ ---
5
+
6
+ # Brownfield Analysis
7
+
8
+ Inspect before editing:
9
+
10
+ - repository and module structure;
11
+ - build, test, lint, and deployment paths;
12
+ - entry points and public interfaces;
13
+ - persistence, migrations, queues, and external integrations;
14
+ - configuration and environment boundaries;
15
+ - tests, telemetry, recent changes, and known failures.
16
+
17
+ Use evidence to distinguish intended behavior, tested behavior, observed behavior, and accidental behavior. Record contradictions instead of resolving them silently.
18
+
19
+ Produce `templates/brownfield-map.md` and identify the smallest safe change seam.
20
+
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: debugging
3
+ description: Investigate failures using reproduction, hypotheses, evidence, and regression protection.
4
+ ---
5
+
6
+ # Debugging
7
+
8
+ Do not modify production code until the failure is understood well enough to state a reproducible symptom.
9
+
10
+ ## Workflow
11
+
12
+ 1. Restate the observed problem and expected behavior.
13
+ 2. Reproduce it with the smallest reliable case.
14
+ 3. List three to seven plausible hypotheses.
15
+ 4. Prioritize the one or two most likely hypotheses using available evidence.
16
+ 5. Collect targeted evidence from code, tests, logs, network, or runtime state.
17
+ 6. Identify the root cause and explain the causal chain.
18
+ 7. Apply the smallest safe fix.
19
+ 8. Add or update a regression test.
20
+ 9. Re-run the related validation and remove temporary diagnostics.
21
+
22
+ ## Report
23
+
24
+ End with:
25
+
26
+ - symptom;
27
+ - root cause;
28
+ - fix;
29
+ - regression protection;
30
+ - validations executed;
31
+ - remaining uncertainty.
32
+
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: planning
3
+ description: Convert an approved specification into small, ordered, independently verifiable implementation tasks.
4
+ ---
5
+
6
+ # Planning
7
+
8
+ - Read the specification, system context, technology inventory, and decisions.
9
+ - Order work by dependency and risk, not by file order.
10
+ - Prefer vertical slices that can be tested and reviewed independently.
11
+ - Give every task a clear change boundary and completion condition.
12
+ - Include migration, compatibility, observability, documentation, and rollback work when applicable.
13
+ - Keep discovery or unresolved decisions out of implementation tasks; route them to a spike or decision record.
14
+
15
+ ## Task contract
16
+
17
+ Each task must include: purpose, files or boundary likely to change, dependencies, test or evidence required, and a definition of done.
18
+
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: product-discovery
3
+ description: Turn a product idea into a testable problem, user outcome, smallest useful slice, and measurable success criteria.
4
+ ---
5
+
6
+ # Product Discovery
7
+
8
+ 1. Identify the user, context, pain, and desired outcome.
9
+ 2. Separate observed evidence from assumptions.
10
+ 3. Define non-goals and constraints.
11
+ 4. Describe the smallest end-to-end slice that can test the central assumption.
12
+ 5. Define success measures and how they will be observed.
13
+ 6. Record unanswered questions and propose spikes when uncertainty is technical.
14
+
15
+ ## Output
16
+
17
+ Create or update `.verdicspec/product-brief.md`. Do not create implementation tasks until the problem, smallest useful slice, and success measures are explicit enough to evaluate.
18
+
19
+ Do not turn an unvalidated idea into a large technical backlog. Product discovery must precede architecture for new products unless a hard constraint requires the reverse.
20
+
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: project-discovery
3
+ description: Build a reliable project baseline before changing a new or existing software product.
4
+ ---
5
+
6
+ # Project Discovery
7
+
8
+ ## Greenfield
9
+
10
+ Inspect the repository and product brief when present, then identify the smallest useful slice, assumptions, constraints, risks, and required technology decisions. If no repository exists, record that fact instead of inventing a baseline.
11
+
12
+ ## Brownfield
13
+
14
+ Inspect the repository, history when useful, build system, tests, runtime configuration, public contracts, data flows, and operational evidence before proposing a change.
15
+
16
+ ## Required baseline
17
+
18
+ - project mode: greenfield, brownfield, or hybrid;
19
+ - product or system purpose;
20
+ - repository map;
21
+ - technology inventory from `technology-discovery`;
22
+ - entry points and important boundaries;
23
+ - commands for build, test, lint, and run;
24
+ - invariants and compatibility constraints;
25
+ - unknowns, risks, and recommended next step.
26
+
27
+ ## Output
28
+
29
+ Create or update `.verdicspec/system-context.md` and coordinate with `technology-discovery`, which creates `.verdicspec/technology-inventory.md`.
30
+
31
+ Do not produce a confident implementation plan when this baseline is missing material information.
32
+
@@ -0,0 +1,13 @@
1
+ ---
2
+ name: requirements
3
+ description: Elicit, structure, prioritize, and validate functional and non-functional requirements for software products.
4
+ ---
5
+
6
+ # Requirements
7
+
8
+ Capture functional behavior, quality attributes, constraints, integrations, data, security, accessibility, operations, and compatibility.
9
+
10
+ For each requirement, record source, priority, rationale, measurable acceptance criteria, and dependencies.
11
+
12
+ Challenge requirements that conflict, are not observable, or prescribe implementation without a justified constraint. Preserve unresolved decisions explicitly instead of silently choosing on behalf of the product owner.
13
+
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: specification
3
+ description: Define a clear, testable software change before implementation.
4
+ ---
5
+
6
+ # Specification
7
+
8
+ Use this skill when a request changes product behavior, architecture, data, APIs, user experience, or operational behavior.
9
+
10
+ ## Outcomes
11
+
12
+ Produce a specification at the depth selected by the workflow. It must contain:
13
+
14
+ 1. Context, problem, users, and desired outcome.
15
+ 2. Project mode and scope: greenfield, brownfield, or hybrid.
16
+ 3. Explicit non-goals and constraints.
17
+ 4. Actors, inputs, outputs, states, and boundaries.
18
+ 5. Functional behavior and edge cases.
19
+ 6. Non-functional requirements: security, privacy, accessibility, performance, reliability, and operations when relevant.
20
+ 7. Acceptance criteria that can be verified.
21
+ 8. Compatibility, migration, rollout, and rollback when changing an existing system.
22
+ 9. Open decisions, assumptions, risks, and a verification plan.
23
+
24
+ ## Rules
25
+
26
+ - Read the existing code and project conventions before proposing implementation details.
27
+ - Separate requirements from solutions.
28
+ - Use observable language; avoid vague terms such as "works correctly".
29
+ - Do not invent production data or undocumented behavior.
30
+ - For brownfield work, describe current behavior and invariants before desired behavior.
31
+ - Prefer vertical slices and incremental delivery over a large speculative design.
32
+ - If an ambiguity materially changes the implementation, record it as an open decision.
33
+
34
+ ## Acceptance criteria format
35
+
36
+ ```text
37
+ Given <precondition>
38
+ When <action>
39
+ Then <observable result>
40
+ ```
41
+
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: spike
3
+ description: Answer a bounded technical question through a time-boxed, evidence-based experiment.
4
+ ---
5
+
6
+ # Spike
7
+
8
+ A spike reduces uncertainty. It is not permission to build production code without a decision.
9
+
10
+ ## Required inputs
11
+
12
+ - question to answer;
13
+ - success criteria;
14
+ - constraints;
15
+ - time or effort budget;
16
+ - alternatives to compare.
17
+
18
+ ## Workflow
19
+
20
+ 1. State the question and what is out of scope.
21
+ 2. Define the smallest experiment that can produce useful evidence.
22
+ 3. Record setup, inputs, observations, and limitations.
23
+ 4. Compare alternatives against the stated criteria.
24
+ 5. Produce a decision, recommendation, or explicit inconclusive result.
25
+ 6. Create a follow-up specification if implementation is approved.
26
+
27
+ ## Prohibited outcome
28
+
29
+ Do not present prototype code as production-ready implementation without separate verification and delivery work.
30
+
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: technology-discovery
3
+ description: Discover the project's languages, frameworks, tools, runtime, and validation commands from repository evidence before selecting technology-specific skills.
4
+ ---
5
+
6
+ # Technology Discovery
7
+
8
+ Run this skill before implementation when the stack is unknown, mixed, or likely to affect the solution.
9
+
10
+ ## Rules
11
+
12
+ - Inspect repository evidence; do not infer technology from the user's wording alone.
13
+ - Prefer manifests, lockfiles, build files, source layout, CI, and documented commands over directory names.
14
+ - Treat a repository as polyglot when multiple production stacks are active.
15
+ - Separate production technologies from test, tooling, generated, and example code.
16
+ - Never install dependencies or execute arbitrary project code during discovery without authorization.
17
+
18
+ ## Evidence map
19
+
20
+ | Evidence | Likely technology or tool |
21
+ |---|---|
22
+ | `package.json`, `tsconfig.json`, lockfiles | Node.js, TypeScript, frontend or backend framework |
23
+ | `.sln`, `.csproj`, `global.json` | .NET / C# |
24
+ | `pom.xml`, `build.gradle`, `build.gradle.kts`, `gradlew` | Java or Kotlin; Maven or Gradle |
25
+ | `pyproject.toml`, `requirements*.txt`, `poetry.lock`, `uv.lock` | Python |
26
+ | `go.mod`, `Cargo.toml`, `composer.json`, `Gemfile`, `Package.swift` | Go, Rust, PHP, Ruby, Swift |
27
+ | `Dockerfile`, compose files, CI workflows | Runtime and delivery environment |
28
+ | test configuration and scripts | Validation tools and project conventions |
29
+
30
+ ## Output
31
+
32
+ Create `templates/technology-inventory.md` containing:
33
+
34
+ - detected languages and versions;
35
+ - frameworks and important libraries;
36
+ - package/build/test/lint commands;
37
+ - runtime and deployment clues;
38
+ - active technology packs;
39
+ - confidence and evidence for every conclusion;
40
+ - unknowns that must be resolved before implementation.
41
+
42
+ If the project is a monorepo, produce one inventory per application or package and a shared infrastructure section.
43
+
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: code-review
3
+ description: Review a change for correctness, regressions, security, maintainability, and missing verification.
4
+ ---
5
+
6
+ # Code Review
7
+
8
+ Review the diff and relevant surrounding code, not only the changed lines.
9
+
10
+ Check, in order:
11
+
12
+ 1. Intended behavior and acceptance criteria.
13
+ 2. Correctness and edge cases.
14
+ 3. Regression and compatibility risk.
15
+ 4. Error handling and security boundaries.
16
+ 5. Data integrity and concurrency.
17
+ 6. Tests and observability.
18
+ 7. Maintainability and unnecessary complexity.
19
+
20
+ Report findings by severity with file, location, impact, and a concrete recommendation. If there are no findings, state what was reviewed and what was not verified.
21
+
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: data-migration
3
+ description: Plan and verify safe schema or data changes with compatibility, rollout, and rollback considerations.
4
+ ---
5
+
6
+ # Data Migration
7
+
8
+ 1. Inventory current schema and data invariants.
9
+ 2. Define the target state and compatibility window.
10
+ 3. Prefer expand-and-contract for live systems.
11
+ 4. Make migration steps observable and restartable where possible.
12
+ 5. Define backfill limits, validation, failure handling, and rollback or forward-fix strategy.
13
+ 6. Test with representative data without exposing production secrets.
14
+
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: observability
3
+ description: Define operational signals that make software behavior diagnosable in development and production.
4
+ ---
5
+
6
+ # Observability
7
+
8
+ Consider observability whenever a change affects a request path, background job, integration, persistence, security boundary, or user-visible failure.
9
+
10
+ Start by writing the operational question: what must an engineer know when this behavior is slow, failing, incorrect, or expensive?
11
+
12
+ ## Signals
13
+
14
+ - Logs: meaningful events with stable fields and safe redaction.
15
+ - Metrics: counters, gauges, and latency distributions tied to operational questions.
16
+ - Traces: causal flow across service and integration boundaries.
17
+ - Errors: actionable classification, context, and correlation identifiers.
18
+
19
+ ## Rules
20
+
21
+ - Do not log secrets, tokens, credentials, or unnecessary personal data.
22
+ - Prefer structured data over strings that cannot be queried.
23
+ - Define the diagnostic question each signal answers.
24
+ - Keep local development and production behavior compatible where practical.
25
+ - Define useful behavior for success, failure, retry, timeout, and degraded operation.
26
+ - Avoid high-cardinality dimensions and uncontrolled payload logging.
27
+ - Prefer correlation that follows a request, job, message, or business operation across boundaries.
28
+
@@ -0,0 +1,11 @@
1
+ # Observability checklist
2
+
3
+ - [ ] What operational question must be answered?
4
+ - [ ] Is the relevant event logged with structured fields?
5
+ - [ ] Are secrets and personal data excluded or redacted?
6
+ - [ ] Is success measurable with a counter or result metric?
7
+ - [ ] Is latency or duration measurable where relevant?
8
+ - [ ] Is failure classified consistently?
9
+ - [ ] Can a request or job be correlated across boundaries?
10
+ - [ ] Is the signal useful in the target environment?
11
+
@@ -0,0 +1,7 @@
1
+ # .NET observability reference
2
+
3
+ - Prefer the existing `ILogger` and `Activity`/OpenTelemetry conventions in the project.
4
+ - Use structured message properties rather than interpolated diagnostic strings.
5
+ - Preserve trace context across HTTP clients, messaging, and background services.
6
+ - Redact credentials, tokens, connection strings, and personal data.
7
+
@@ -0,0 +1,9 @@
1
+ # Java observability reference
2
+
3
+ - Prefer the project's existing logging facade and telemetry conventions.
4
+ - Use structured fields and stable event names rather than concatenated messages.
5
+ - Preserve context across servlet or reactive requests, executors, schedulers, messaging, and database calls.
6
+ - Redact authorization headers, cookies, credentials, tokens, connection strings, and personal data.
7
+ - Treat blocking calls, retries, timeouts, and thread-pool saturation as operational signals where relevant.
8
+ - If OpenTelemetry is present, preserve trace and span context across service boundaries without creating uncontrolled cardinality.
9
+
@@ -0,0 +1,7 @@
1
+ # Node.js observability reference
2
+
3
+ - Prefer the project's existing logger and telemetry libraries.
4
+ - Use structured JSON in production and readable output locally when supported.
5
+ - Preserve async context across HTTP, jobs, and external calls.
6
+ - Redact authorization headers, cookies, tokens, and sensitive payload fields.
7
+
@@ -0,0 +1,7 @@
1
+ # Python observability reference
2
+
3
+ - Prefer the project's existing logging and telemetry stack.
4
+ - Use structured fields and stable event names.
5
+ - Preserve context across async tasks, workers, HTTP clients, and queues.
6
+ - Redact credentials, tokens, personal data, and full request bodies unless explicitly required.
7
+
@@ -0,0 +1,16 @@
1
+ # Logging plan
2
+
3
+ ## Diagnostic question
4
+
5
+ What question should an operator answer from logs?
6
+
7
+ ## Events
8
+
9
+ | Event | Level | Required fields | Redaction |
10
+ |---|---|---|---|
11
+ | | | | |
12
+
13
+ ## Failure behavior
14
+
15
+ -
16
+
@@ -0,0 +1,6 @@
1
+ # Metrics plan
2
+
3
+ | Metric | Type | Dimensions | Question answered |
4
+ |---|---|---|---|
5
+ | | Counter / Gauge / Histogram | | |
6
+
@@ -0,0 +1,14 @@
1
+ # Tracing plan
2
+
3
+ ## Boundaries
4
+
5
+ List service, job, database, queue, and external integration boundaries.
6
+
7
+ ## Span attributes
8
+
9
+ Only include low-cardinality, non-sensitive attributes that help explain latency or failure.
10
+
11
+ ## Correlation
12
+
13
+ Describe how trace, log, and request identifiers relate.
14
+
@@ -0,0 +1,17 @@
1
+ ---
2
+ name: pull-request
3
+ description: Prepare a reviewable pull request with scope, evidence, risks, and reviewer guidance.
4
+ ---
5
+
6
+ # Pull Request
7
+
8
+ - Keep the change focused and split unrelated work.
9
+ - Link the specification, issue, or decision record.
10
+ - Summarize behavior instead of narrating every edit.
11
+ - List exact validation commands and results.
12
+ - State known limitations, rollout risk, and rollback strategy.
13
+ - Call out migrations, configuration, security, or observability changes.
14
+ - Do not describe unexecuted checks as passing.
15
+
16
+ Use `templates/pull-request.md` as the default structure.
17
+
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: release-readiness
3
+ description: Determine whether a change can be delivered safely with rollout, rollback, migration, and operational evidence.
4
+ ---
5
+
6
+ # Release Readiness
7
+
8
+ Check:
9
+
10
+ - acceptance criteria and verification status;
11
+ - build, tests, lint, and security checks;
12
+ - configuration and secret requirements;
13
+ - data or schema migration safety;
14
+ - backward compatibility;
15
+ - observability and alerting;
16
+ - rollout controls and rollback path;
17
+ - documentation and support readiness.
18
+
19
+ Create `.verdicspec/reports/<change-id>-release-readiness.md` and return `Ready`, `Ready with explicit risk`, or `Not ready`, with evidence for the decision.
20
+
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: security
3
+ description: Identify and reduce security, privacy, abuse, and supply-chain risks in a software change.
4
+ ---
5
+
6
+ # Security
7
+
8
+ Consider trust boundaries, authentication, authorization, input handling, secrets, sensitive data, dependency risk, logging exposure, abuse cases, and failure behavior.
9
+
10
+ For high-risk changes, produce `.verdicspec/reports/<change-id>-threat-model.md` from `templates/threat-model.md`, with assets, actors, entry points, threats, mitigations, verification, and residual risk. Do not treat passing tests as proof that security risk is absent.
11
+
@@ -0,0 +1,37 @@
1
+ ---
2
+ name: testing
3
+ description: Design and execute tests that verify behavior and protect against regressions.
4
+ ---
5
+
6
+ # Testing
7
+
8
+ Derive tests from requirements and acceptance criteria, not from the implementation after it is written.
9
+
10
+ ## Test selection
11
+
12
+ - Unit: pure rules, transformations, and local decisions.
13
+ - Integration: persistence, queues, frameworks, filesystem, and external boundaries under controlled conditions.
14
+ - Contract: public APIs, events, schemas, and compatibility promises.
15
+ - End-to-end: critical user journeys through real application boundaries.
16
+ - Exploratory: unknown behavior, usability, and failure discovery; record the observation.
17
+
18
+ Prefer the narrowest test that proves the behavior, then add broader tests when integration risk requires them.
19
+
20
+ ## Required coverage
21
+
22
+ - happy path;
23
+ - invalid input and authorization failures;
24
+ - boundaries, empty states, timeouts, retries, and partial failure;
25
+ - compatibility behavior for brownfield changes;
26
+ - regression protection for bug fixes;
27
+ - deterministic setup and cleanup.
28
+
29
+ Preserve the project's test style and framework unless there is a concrete reason to change it. Never claim a test passed unless it was executed.
30
+
31
+ ## Completion checklist
32
+
33
+ - Tests cover the changed behavior.
34
+ - Regression coverage exists for fixed bugs.
35
+ - Relevant existing tests were executed.
36
+ - Failures are reported with their actual output and scope.
37
+
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: verification
3
+ description: Verify that an implementation satisfies its specification and report evidence honestly.
4
+ ---
5
+
6
+ # Verification
7
+
8
+ Build a criterion-to-evidence matrix. Use the cheapest reliable check first, then broaden validation according to risk and project depth.
9
+
10
+ Evidence may include executed tests, lint, build output, static analysis, manual inspection, runtime checks, or independent review.
11
+
12
+ Verify both changed behavior and preserved behavior for brownfield work. For greenfield work, verify the smallest useful slice through real boundaries.
13
+
14
+ Classify every result as `Verified`, `Failed`, `Not run`, `Blocked`, or `Assumed`. Never convert an assumption into a verification claim.
15
+
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: brownfield-change
3
+ description: Safely change an existing product by mapping current behavior, preserving invariants, and delivering a reversible increment.
4
+ ---
5
+
6
+ # Brownfield Change
7
+
8
+ Compose `project-discovery`, `technology-discovery`, `brownfield-analysis`, `specification`, `architecture`, `planning`, `testing`, `observability`, `data-migration` when relevant, `code-review`, `verification`, and `release-readiness`.
9
+
10
+ ## Sequence
11
+
12
+ 1. Map the current system and confirm the project baseline.
13
+ 2. Identify behavior, contracts, data, and operational invariants.
14
+ 3. Define the delta and compatibility requirements.
15
+ 4. Choose the smallest change seam and migration strategy.
16
+ 5. Implement in reversible increments.
17
+ 6. Verify new behavior and preserved behavior.
18
+ 7. Prepare rollout, rollback, and operational evidence.
19
+
20
+ ## Outputs and gates
21
+
22
+ - Baseline: `.verdicspec/system-context.md` and `.verdicspec/technology-inventory.md`.
23
+ - Change: `.verdicspec/specifications/<change-id>.md` and `.verdicspec/plans/<change-id>.md`.
24
+ - Compatibility: invariants and migration strategy reviewed.
25
+ - Delivery: verification and release-readiness reports complete.
26
+