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: 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,242 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { existsSync, cpSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
4
+ import { dirname, join, resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
8
+ const commonEntries = [
9
+ 'AGENTS.md',
10
+ '.verdicspec',
11
+ 'agents',
12
+ 'commands',
13
+ 'docs',
14
+ 'skills',
15
+ 'technology-packs',
16
+ 'templates'
17
+ ];
18
+
19
+ const adapters = {
20
+ codex: ['AGENTS.md', '.agents-bundle'],
21
+ antigravity: ['AGENTS.md', '.agents-bundle'],
22
+ claude: ['CLAUDE.md', '.claude-bundle'],
23
+ cursor: ['.cursor'],
24
+ copilot: ['.github/copilot-instructions.md', '.agents-bundle'],
25
+ gemini: ['GEMINI.md'],
26
+ cline: ['.clinerules']
27
+ };
28
+
29
+ function usage() {
30
+ console.log(`Verdicspec CLI
31
+
32
+ Usage:
33
+ verdicspec init [directory] [--tool all|codex|claude|cursor|antigravity|copilot|gemini|cline] [--force]
34
+ verdicspec validate
35
+ verdicspec list
36
+ verdicspec doctor [directory]
37
+ verdicspec inspect [directory]
38
+ verdicspec help
39
+
40
+ Examples:
41
+ verdicspec init .
42
+ verdicspec init C:\\projects\\my-app --tool all
43
+ verdicspec init . --tool cursor --force
44
+ `);
45
+ }
46
+
47
+ function parseOptions(args) {
48
+ const options = { force: false, tool: 'all', positional: [] };
49
+ for (let index = 0; index < args.length; index += 1) {
50
+ const value = args[index];
51
+ if (value === '--force') options.force = true;
52
+ else if (value === '--tool') options.tool = args[++index] ?? '';
53
+ else if (value === '--help' || value === '-h') options.help = true;
54
+ else options.positional.push(value);
55
+ }
56
+ return options;
57
+ }
58
+
59
+ function copyEntry(sourceRelative, targetRoot, force, destinationRelative = sourceRelative) {
60
+ const source = join(packageRoot, sourceRelative);
61
+ const destination = join(targetRoot, destinationRelative);
62
+ if (!existsSync(source)) throw new Error(`Package entry not found: ${sourceRelative}`);
63
+ if (existsSync(destination) && !force) {
64
+ console.log(`Skipped existing path: ${destination}`);
65
+ return;
66
+ }
67
+ mkdirSync(dirname(destination), { recursive: true });
68
+ cpSync(source, destination, { recursive: true, force });
69
+ console.log(`Installed: ${destination}`);
70
+ }
71
+
72
+ function installAgentsBundle(targetRoot, toolRoot, force) {
73
+ copyEntry('agents', targetRoot, force, join(toolRoot, 'agents'));
74
+ copyEntry('skills', targetRoot, force, join(toolRoot, 'skills'));
75
+ const rulesSource = join(packageRoot, '.agents', 'rules');
76
+ if (existsSync(rulesSource)) {
77
+ copyEntry(join('.agents', 'rules'), targetRoot, force, join(toolRoot, 'rules'));
78
+ }
79
+ }
80
+
81
+ function copyAdapter(adapter, targetRoot, force) {
82
+ for (const entry of adapters[adapter]) {
83
+ if (entry === '.agents-bundle') {
84
+ installAgentsBundle(targetRoot, '.agents', force);
85
+ } else if (entry === '.claude-bundle') {
86
+ installAgentsBundle(targetRoot, '.claude', force);
87
+ } else {
88
+ copyEntry(entry, targetRoot, force);
89
+ }
90
+ }
91
+ }
92
+
93
+ function init(args) {
94
+ const options = parseOptions(args);
95
+ if (options.help) return usage();
96
+ const allowedTools = ['all', ...Object.keys(adapters)];
97
+ if (!allowedTools.includes(options.tool)) throw new Error(`Invalid tool. Use: ${allowedTools.join(', ')}`);
98
+ const targetRoot = resolve(options.positional[0] ?? '.');
99
+ mkdirSync(targetRoot, { recursive: true });
100
+ for (const entry of commonEntries) copyEntry(entry, targetRoot, options.force);
101
+ const selected = options.tool === 'all' ? Object.keys(adapters) : [options.tool];
102
+ for (const adapter of selected) copyAdapter(adapter, targetRoot, options.force);
103
+ console.log(`Verdicspec installed in ${targetRoot}`);
104
+ }
105
+
106
+ function list() {
107
+ const skills = [];
108
+ for (const category of readdirSync(join(packageRoot, 'skills'))) {
109
+ const categoryPath = join(packageRoot, 'skills', category);
110
+ if (!existsSync(categoryPath) || !statSync(categoryPath).isDirectory()) continue;
111
+ for (const skill of readdirSync(categoryPath)) {
112
+ if (existsSync(join(categoryPath, skill, 'SKILL.md'))) skills.push(`${category}/${skill}`);
113
+ }
114
+ }
115
+ console.log('Commands:');
116
+ for (const command of readdirSync(join(packageRoot, 'commands')).filter((entry) => entry.endsWith('.md'))) {
117
+ console.log(` verdicspec ${command.replace(/\.md$/, '')}`);
118
+ }
119
+ console.log('\nAgents:');
120
+ for (const agent of readdirSync(join(packageRoot, 'agents')).filter((entry) => entry.endsWith('.md')).sort()) {
121
+ console.log(` ${agent.replace(/\.md$/, '')}`);
122
+ }
123
+ console.log('\nSkills:');
124
+ for (const skill of skills.sort()) console.log(` ${skill}`);
125
+ }
126
+
127
+ function validate() {
128
+ const skillsRoot = join(packageRoot, 'skills');
129
+ const skills = [];
130
+ for (const category of readdirSync(skillsRoot)) {
131
+ const categoryPath = join(skillsRoot, category);
132
+ if (!statSync(categoryPath).isDirectory()) continue;
133
+ for (const skill of readdirSync(categoryPath)) {
134
+ const file = join(categoryPath, skill, 'SKILL.md');
135
+ if (!existsSync(file)) continue;
136
+ const content = readFileSync(file, 'utf8');
137
+ if (!/^---\s*\nname: .+\ndescription: .+\n---/s.test(content)) {
138
+ throw new Error(`Invalid skill frontmatter: ${file}`);
139
+ }
140
+ skills.push(skill);
141
+ }
142
+ }
143
+ if (new Set(skills).size !== skills.length) throw new Error('Duplicate skill directory name detected');
144
+ const agentsDir = join(packageRoot, 'agents');
145
+ const agents = readdirSync(agentsDir).filter((entry) => entry.endsWith('.md'));
146
+ if (agents.length < 10) throw new Error(`Expected at least 10 agents, found ${agents.length}`);
147
+ for (const required of ['AGENTS.md', 'templates/feature-spec.md', 'technology-packs/java/README.md', 'agents/debugger.md']) {
148
+ if (!existsSync(join(packageRoot, required))) throw new Error(`Missing required entry: ${required}`);
149
+ }
150
+ for (const mirror of ['.cursor/agents', '.claude/agents', '.agents/agents']) {
151
+ if (!existsSync(join(packageRoot, mirror, 'debugger.md'))) {
152
+ throw new Error(`Missing mirrored agent: ${mirror}/debugger.md`);
153
+ }
154
+ }
155
+ console.log(`Validation passed: ${skills.length} skills, ${agents.length} agents.`);
156
+ }
157
+
158
+ function doctor(args) {
159
+ const targetRoot = resolve(args[0] ?? '.');
160
+ const checks = ['AGENTS.md', '.verdicspec/config.json', 'skills', 'technology-packs', 'templates', 'commands', 'agents'];
161
+ const missing = checks.filter((entry) => !existsSync(join(targetRoot, entry)));
162
+ if (missing.length > 0) {
163
+ console.error(`Verdicspec is not installed correctly in ${targetRoot}`);
164
+ for (const entry of missing) console.error(`Missing: ${entry}`);
165
+ process.exitCode = 1;
166
+ return;
167
+ }
168
+ console.log(`Verdicspec is installed in ${targetRoot}`);
169
+ }
170
+
171
+ const ignoredDirectories = new Set(['.git', '.verdicspec', 'node_modules', 'target', 'build', 'dist', '.venv', 'venv', '__pycache__']);
172
+ const evidence = [
173
+ ['package.json', 'Node.js', 'package manifest'],
174
+ ['tsconfig.json', 'TypeScript', 'TypeScript configuration'],
175
+ ['pom.xml', 'Java / Maven', 'Maven build descriptor'],
176
+ ['build.gradle', 'Java or Kotlin / Gradle', 'Gradle build descriptor'],
177
+ ['build.gradle.kts', 'Kotlin or Java / Gradle', 'Kotlin Gradle build descriptor'],
178
+ ['gradlew', 'Java or Kotlin / Gradle', 'Gradle wrapper'],
179
+ ['pyproject.toml', 'Python', 'Python project manifest'],
180
+ ['requirements.txt', 'Python', 'Python dependency file'],
181
+ ['go.mod', 'Go', 'Go module manifest'],
182
+ ['Cargo.toml', 'Rust', 'Cargo manifest'],
183
+ ['composer.json', 'PHP', 'Composer manifest'],
184
+ ['Gemfile', 'Ruby', 'Ruby dependency manifest'],
185
+ ['Package.swift', 'Swift', 'Swift package manifest']
186
+ ];
187
+
188
+ function walkFiles(root, depth = 0, result = []) {
189
+ if (depth > 3) return result;
190
+ for (const entry of readdirSync(root, { withFileTypes: true })) {
191
+ if (entry.isDirectory() && !ignoredDirectories.has(entry.name)) {
192
+ walkFiles(join(root, entry.name), depth + 1, result);
193
+ } else if (entry.isFile()) {
194
+ result.push(join(root, entry.name));
195
+ }
196
+ }
197
+ return result;
198
+ }
199
+
200
+ function inspect(args) {
201
+ const targetRoot = resolve(args[0] ?? '.');
202
+ if (!existsSync(targetRoot) || !statSync(targetRoot).isDirectory()) throw new Error(`Directory not found: ${targetRoot}`);
203
+ const files = walkFiles(targetRoot);
204
+ const findings = [];
205
+ for (const [fileName, technology, reason] of evidence) {
206
+ const matches = files.filter((file) => file.endsWith(`\\${fileName}`) || file.endsWith(`/${fileName}`));
207
+ if (matches.length > 0) findings.push({ technology, reason, files: matches.map((file) => file.slice(targetRoot.length + 1)) });
208
+ }
209
+ const lines = [
210
+ '# Technology Inventory',
211
+ '',
212
+ `- Project: ${targetRoot}`,
213
+ '- Mode: To be classified as greenfield, brownfield, or hybrid',
214
+ '',
215
+ '## Detected technologies',
216
+ '',
217
+ '| Technology | Evidence | Confidence |',
218
+ '|---|---|---|'
219
+ ];
220
+ if (findings.length === 0) lines.push('| No known technology detected | Inspect repository manually | Low |');
221
+ for (const finding of findings) lines.push(`| ${finding.technology} | ${finding.reason}: ${finding.files.join(', ')} | Medium |`);
222
+ lines.push('', '## Commands to confirm', '', '| Purpose | Command | Confirmed? |', '|---|---|---|', '| Install | | No |', '| Run | | No |', '| Test | | No |', '| Lint | | No |', '| Build | | No |', '', '## Unknowns', '', '- Confirm versions, active modules, and project-specific commands before implementation.');
223
+ const artifactRoot = join(targetRoot, '.verdicspec');
224
+ mkdirSync(artifactRoot, { recursive: true });
225
+ const output = join(artifactRoot, 'technology-inventory.md');
226
+ writeFileSync(output, `${lines.join('\n')}\n`, 'utf8');
227
+ console.log(`Technology inventory written to ${output}`);
228
+ for (const finding of findings) console.log(`Detected: ${finding.technology}`);
229
+ }
230
+
231
+ const [command = 'help', ...args] = process.argv.slice(2);
232
+ try {
233
+ if (command === 'init') init(args);
234
+ else if (command === 'validate') validate();
235
+ else if (command === 'list') list();
236
+ else if (command === 'doctor') doctor(args);
237
+ else if (command === 'inspect') inspect(args);
238
+ else usage();
239
+ } catch (error) {
240
+ console.error(`Error: ${error.message}`);
241
+ process.exitCode = 1;
242
+ }
@@ -0,0 +1,4 @@
1
+ # verdicspec debug
2
+
3
+ Load `skills/core/debugging`, `skills/practices/testing`, and `skills/practices/observability` when relevant. Reproduce, hypothesize, collect evidence, identify root cause, apply the smallest fix, and verify regression protection.
4
+
@@ -0,0 +1,4 @@
1
+ # verdicspec discover
2
+
3
+ Load `skills/core/project-discovery`, `skills/core/technology-discovery`, and `skills/core/product-discovery` when the request concerns a new product. Determine greenfield, brownfield, or hybrid mode, then create the appropriate baseline artifacts.
4
+
@@ -0,0 +1,4 @@
1
+ # verdicspec map
2
+
3
+ Load `skills/core/project-discovery`, `skills/core/technology-discovery`, and `skills/core/brownfield-analysis`. Inspect the existing product before proposing a change and create `templates/brownfield-map.md` from repository evidence.
4
+
@@ -0,0 +1,4 @@
1
+ # verdicspec plan
2
+
3
+ Load `skills/core/planning`, `skills/core/architecture`, and the active technology pack. Convert an approved specification into ordered tasks with dependencies and independent completion evidence.
4
+
package/commands/pr.md ADDED
@@ -0,0 +1,4 @@
1
+ # verdicspec pr
2
+
3
+ Load `skills/practices/pull-request` and `templates/pull-request.md`. Prepare a focused, reviewable pull request with exact validation evidence, risks, rollout, rollback, and reviewer focus.
4
+
@@ -0,0 +1,4 @@
1
+ # verdicspec review
2
+
3
+ Load `skills/practices/code-review`. Review the complete change against the specification, surrounding code, risk boundaries, tests, security, observability, and maintainability. Report findings by severity.
4
+
@@ -0,0 +1,4 @@
1
+ # verdicspec specify
2
+
3
+ Load `skills/core/specification` and `skills/core/requirements`. Create or refine a specification with requirements, acceptance criteria, risks, non-goals, and a verification plan.
4
+
@@ -0,0 +1,4 @@
1
+ # verdicspec spike
2
+
3
+ Load `skills/core/spike` and the relevant technology pack. Run a bounded experiment, record evidence and limitations, and produce a decision or an explicit inconclusive result.
4
+
@@ -0,0 +1,4 @@
1
+ # verdicspec verify
2
+
3
+ Load `skills/practices/verification`, `skills/practices/testing`, and `skills/practices/release-readiness` when delivery is involved. Map every acceptance criterion to actual evidence and classify unexecuted checks honestly.
4
+
@@ -0,0 +1,22 @@
1
+ # Artifact contract
2
+
3
+ The project-local `.verdicspec/` directory is the durable state of the method. Tool adapters and chat history are transport layers; they are not the source of truth.
4
+
5
+ ## Required artifacts by depth
6
+
7
+ | Depth | Required artifacts |
8
+ |---|---|
9
+ | L0 | Verification note in the final response |
10
+ | L1 | Specification, implementation plan, test plan, verification report |
11
+ | L2 | System context, change proposal, decision records, test plan, observability plan, verification report |
12
+ | L3 | Product brief, system context, technology inventory, requirements, architecture decisions, delivery increments, threat model, verification and release reports |
13
+
14
+ ## Naming
15
+
16
+ - Specifications: `.verdicspec/specifications/<change-id>.md`
17
+ - Decisions: `.verdicspec/decisions/ADR-<number>-<slug>.md`
18
+ - Plans: `.verdicspec/plans/<change-id>.md`
19
+ - Reports: `.verdicspec/reports/<change-id>-<report-type>.md`
20
+
21
+ Use stable IDs such as `REQ-001`, `AC-001`, `TASK-001`, `TEST-001`, and `THR-001` to preserve traceability.
22
+
@@ -0,0 +1,32 @@
1
+ # Verdicspec commands
2
+
3
+ These are tool-independent commands. A tool adapter may expose them as slash commands, chat prompts, or task templates, but the semantics remain the same.
4
+
5
+ | Command | Purpose | Primary mode |
6
+ |---|---|---|
7
+ | `verdicspec discover` | Understand the problem, users, constraints, and existing context | Greenfield / Brownfield |
8
+ | `verdicspec map` | Map an existing codebase, system, contracts, and risks | Brownfield |
9
+ | `verdicspec inspect` | Detect technology evidence and write `.verdicspec/technology-inventory.md` | Any |
10
+ | `verdicspec specify` | Create or refine a testable change specification | Any |
11
+ | `verdicspec design` | Produce architecture, decisions, and trade-offs | L2 / L3 |
12
+ | `verdicspec plan` | Decompose approved work into ordered, verifiable tasks | Any non-trivial change |
13
+ | `verdicspec build` | Implement the approved plan using the selected technology pack | Any |
14
+ | `verdicspec test` | Derive and execute the relevant test strategy | Any |
15
+ | `verdicspec debug` | Investigate a failure using hypotheses and evidence | Bug fix / incident |
16
+ | `verdicspec spike` | Answer a bounded technical question through an experiment | Any |
17
+ | `verdicspec verify` | Map acceptance criteria to executed evidence | Any |
18
+ | `verdicspec review` | Perform an independent change review | Any reviewable change |
19
+ | `verdicspec pr` | Prepare a focused pull request | Delivery |
20
+ | `verdicspec status` | Report artifacts, gate, risks, and remaining work | Any |
21
+
22
+ ## Command contract
23
+
24
+ Every command must state:
25
+
26
+ - inputs it read;
27
+ - artifacts it created or changed;
28
+ - decisions it made;
29
+ - validations it executed;
30
+ - blockers and assumptions;
31
+ - the next gate.
32
+
@@ -0,0 +1,32 @@
1
+ # Method Overview
2
+
3
+ Verdicspec treats software development as a sequence of explicit decisions and verifiable outcomes.
4
+
5
+ ```text
6
+ Understand → Specify → Plan → Implement → Verify → Review → Deliver
7
+ ```
8
+
9
+ The sequence is adaptive. Small, low-risk changes may use a lightweight path. Ambiguous, risky, or cross-cutting changes should use the complete workflow.
10
+
11
+ The method first classifies the project as greenfield, brownfield, or hybrid and then discovers the actual technology stack. This prevents the agent from applying a generic workflow or the wrong framework assumptions to the repository.
12
+
13
+ See [the complete workflow](workflow.md), [project modes](project-modes.md), and [portable commands](commands.md).
14
+
15
+ ## Work modes
16
+
17
+ - Feature development: deliver new behavior.
18
+ - Bug fixing: restore intended behavior and add regression protection.
19
+ - Debugging: investigate an observed failure before changing implementation.
20
+ - Spike: answer a bounded technical question without pretending the experiment is production code.
21
+ - Refactoring: improve structure while preserving behavior.
22
+
23
+ ## Evidence standard
24
+
25
+ Every completed work item should identify:
26
+
27
+ - what was requested;
28
+ - what changed;
29
+ - what was verified;
30
+ - what remains assumed or unverified;
31
+ - which validation commands were executed and their results.
32
+
@@ -0,0 +1,68 @@
1
+ # npm CI/CD
2
+
3
+ The repository has three GitHub Actions workflows:
4
+
5
+ - `ci.yml`: validates pushes and pull requests.
6
+ - `publish.yml`: provides an optional manual OIDC publish path.
7
+ - `release.yml`: increments the patch version, publishes, tags, and creates a GitHub Release after package changes reach `main`.
8
+
9
+ ## One-time setup
10
+
11
+ 1. Create or confirm the npm package name.
12
+ 2. Ensure the package metadata points to this GitHub repository.
13
+ 3. Create an npm access token with permission to publish this package.
14
+ 4. In GitHub, open `Settings → Secrets and variables → Actions` and create:
15
+
16
+ ```text
17
+ Name: NPM_TOKEN
18
+ Value: <the npm access token>
19
+ ```
20
+
21
+ 5. Create the GitHub environment named `npm`.
22
+ 6. If you prefer tokenless publishing, configure npm Trusted Publishing instead. On npmjs.com, open the package settings and add a GitHub Actions Trusted Publisher.
23
+ 7. Configure:
24
+ - owner: `luismpenholato`;
25
+ - repository: `verdicspec`;
26
+ - workflow filename: `publish.yml`;
27
+ - environment: `npm`.
28
+ 8. Add approval rules to the `npm` environment if you want a human gate before publication.
29
+
30
+ The automatic `release-on-main.yml` workflow uses `NPM_TOKEN`. The tag-based `publish.yml` workflow uses OIDC Trusted Publishing and does not require `NPM_TOKEN`.
31
+
32
+ ## Release process
33
+
34
+ For automatic releases, merge a package change into `main`. The workflow will:
35
+
36
+ 1. Validate the package and run tests.
37
+ 2. Increment the patch version.
38
+ 3. Publish the package using `NPM_TOKEN`.
39
+ 4. Commit the new `package.json` and `package-lock.json`.
40
+ 5. Create a `vX.Y.Z` tag.
41
+ 6. Create a GitHub Release with generated notes.
42
+
43
+ For a controlled manual release, update the version and create a tag:
44
+
45
+ ```powershell
46
+ npm version patch
47
+ git push origin main --follow-tags
48
+ ```
49
+
50
+ For a minor or major release:
51
+
52
+ ```powershell
53
+ npm version minor
54
+ npm version major
55
+ ```
56
+
57
+ The release workflow pushes an annotated version tag and creates the GitHub Release after publication. The tag does not trigger a second npm publication.
58
+
59
+ For the optional tokenless path, run `publish.yml` manually after configuring npm Trusted Publishing for the repository and workflow.
60
+
61
+ ## Local checks
62
+
63
+ ```powershell
64
+ npm run validate
65
+ npm pack --dry-run
66
+ ```
67
+
68
+ Do not place npm tokens in the repository, workflow file, or `.npmrc` committed to source control.
@@ -0,0 +1,34 @@
1
+ # Portable adapters
2
+
3
+ Verdicspec has one canonical source and thin tool adapters.
4
+
5
+ ## Canonical source
6
+
7
+ - Instructions: `AGENTS.md`
8
+ - Agents: `agents/*.md`
9
+ - Skills: `skills/**/SKILL.md`
10
+ - Technology packs: `technology-packs/`
11
+ - Templates: `templates/`
12
+ - Commands: `commands/`
13
+ - Artifacts root: `.verdicspec/`
14
+
15
+ ## Supported entry points
16
+
17
+ | Tool | Rules / instructions | Agents | Skills |
18
+ |---|---|---|---|
19
+ | Cursor | `.cursor/rules/*.mdc` | `.cursor/agents/` | `.cursor/skills/` or `skills/` |
20
+ | Claude Code | `CLAUDE.md` + `.claude/rules/` | `.claude/agents/` | `.claude/skills/` |
21
+ | OpenAI Codex | `AGENTS.md` | `.agents/agents/` | `.agents/skills/` or `skills/` |
22
+ | Antigravity | `.agents/rules/` + `AGENTS.md` | `.agents/agents/` | `.agents/skills/` |
23
+ | GitHub Copilot | `.github/copilot-instructions.md` | — | `.agents/skills/` |
24
+ | Gemini CLI | `GEMINI.md` | — | points to canonical skills |
25
+ | Cline | `.clinerules/verdicspec.md` | — | points to canonical skills |
26
+
27
+ Install with:
28
+
29
+ ```powershell
30
+ npm i -g verdicspec
31
+ verdicspec init . --tool all
32
+ ```
33
+
34
+ Adapters stay short. They discover agents/skills and delegate to the canonical method so behavior does not fork between tools.
@@ -0,0 +1,33 @@
1
+ # Project modes
2
+
3
+ ## Greenfield
4
+
5
+ Use when the product or subsystem does not have a reliable implementation baseline.
6
+
7
+ 1. Define the problem, users, value, and non-goals.
8
+ 2. Identify the smallest useful product slice.
9
+ 3. Define domain concepts, user journeys, and acceptance criteria.
10
+ 4. Choose architecture and technology only after constraints are known.
11
+ 5. Create the first vertical slice with tests and operational signals.
12
+ 6. Validate with real feedback before expanding scope.
13
+
14
+ Do not create a large platform architecture before the first useful slice proves the important assumptions.
15
+
16
+ ## Brownfield
17
+
18
+ Use when an existing product, codebase, API, database, or operational system must be changed.
19
+
20
+ 1. Map the current system before proposing a target design.
21
+ 2. Identify ownership, boundaries, dependencies, data flows, and undocumented behavior.
22
+ 3. Write invariants: behavior that MUST remain unchanged.
23
+ 4. Define the delta between current and desired state.
24
+ 5. Choose a migration and rollback strategy.
25
+ 6. Implement in reversible increments.
26
+ 7. Verify both the new behavior and compatibility with the existing behavior.
27
+
28
+ Brownfield work must never treat the specification as the only source of truth. The running system, tests, telemetry, contracts, and user behavior are evidence too.
29
+
30
+ ## Hybrid
31
+
32
+ Use when a new product is being introduced into an existing organization or platform. Apply greenfield product framing and brownfield integration mapping together.
33
+
@@ -0,0 +1,25 @@
1
+ # Specification standard
2
+
3
+ ## Required sections
4
+
5
+ Every non-trivial change should define:
6
+
7
+ 1. Context and problem.
8
+ 2. Desired outcome.
9
+ 3. Scope and non-goals.
10
+ 4. Constraints and invariants.
11
+ 5. Behavioral requirements.
12
+ 6. Acceptance criteria.
13
+ 7. Risks and open decisions.
14
+ 8. Verification plan.
15
+
16
+ ## Requirement quality
17
+
18
+ Requirements must be observable, testable, and independent of implementation details unless the implementation constraint is intentional.
19
+
20
+ Use MUST for mandatory behavior, SHOULD for a justified default, and MAY for optional behavior.
21
+
22
+ ## Traceability
23
+
24
+ Use stable identifiers such as `REQ-001`, `AC-001`, and `TEST-001`. Verification should map acceptance criteria to tests, checks, inspection, or explicit human review.
25
+
@@ -0,0 +1,24 @@
1
+ # Tool and model support
2
+
3
+ ## GPT and Codex
4
+
5
+ GPT is the model. Codex is the coding-agent environment that reads the repository, edits files, runs commands, and applies project instructions.
6
+
7
+ Verdicspec supports Codex through the root `AGENTS.md`. It can be used with GPT models selected by Codex because the method is expressed as Markdown skills and repository artifacts, not as model-specific API calls.
8
+
9
+ ChatGPT or the GPT API by itself does not automatically inspect a local repository or execute the method. It needs a host application, agent harness, or integration that provides the repository files and exposes the relevant skills and commands.
10
+
11
+ ## Support matrix
12
+
13
+ | Environment | Entry point | Level |
14
+ |---|---|---|
15
+ | OpenAI Codex / ChatGPT Codex | `AGENTS.md` | Native repository instructions |
16
+ | GPT through another agent host | Host-specific adapter | Supported when the host loads the files |
17
+ | Claude Code | `CLAUDE.md`, `.claude/skills/` | Native adapter and skills |
18
+ | Cursor | `.cursor/rules/` | Native rules adapter |
19
+ | GitHub Copilot | `.github/copilot-instructions.md`, `.agents/skills/` | Native instructions and skills |
20
+ | Gemini CLI | `GEMINI.md` | Native context adapter |
21
+ | Cline | `.clinerules/` | Native workspace rules adapter |
22
+
23
+ The portable contract is the same in every environment: read the repository contract, discover the project technology, select the workflow, load only the required skills, and report evidence.
24
+
@@ -0,0 +1,45 @@
1
+ # Verdicspec workflow
2
+
3
+ Verdicspec is an adaptive SDD method. It does not force the same ceremony on a landing page, a payment flow, and a distributed migration.
4
+
5
+ ## Lifecycle
6
+
7
+ ```text
8
+ Discover → Frame → Specify → Design → Plan → Build → Verify → Review → Deliver → Learn
9
+ ```
10
+
11
+ Each phase has an output and a gate. The agent may move forward only when the gate is satisfied or the remaining uncertainty is explicitly accepted.
12
+
13
+ Choose the lowest level that honestly covers the risk. Increase the level when ambiguity, blast radius, security impact, data migration, or operational consequence increases. Never reduce the level only to avoid creating required evidence.
14
+
15
+ ## Depth levels
16
+
17
+ ### L0 — Trivial
18
+
19
+ Use for isolated, low-risk changes with obvious behavior. Read the relevant code, make the change, run a focused check, and report evidence.
20
+
21
+ ### L1 — Focused change
22
+
23
+ Use for a normal feature or bug fix. Create a short change specification, acceptance criteria, implementation plan, tests, and verification report.
24
+
25
+ ### L2 — Complex change
26
+
27
+ Use for cross-module behavior, public APIs, persistence, integrations, security, or operational impact. Add system context, architecture decisions, risk analysis, observability, migration/rollback planning, and independent review.
28
+
29
+ ### L3 — Product or system initiative
30
+
31
+ Use for a new product, major subsystem, platform, or high-risk change. Add product framing, domain model, user journeys, non-functional requirements, threat model, delivery increments, and explicit human approval gates.
32
+
33
+ ## Gates
34
+
35
+ | Gate | Question | Minimum evidence |
36
+ |---|---|---|
37
+ | Frame | Are we solving the right problem? | Problem, users, outcome, non-goals |
38
+ | Specify | Is the desired behavior unambiguous? | Requirements and acceptance criteria |
39
+ | Design | Is the solution compatible with the system? | Architecture and decisions |
40
+ | Plan | Can the work be implemented and verified incrementally? | Ordered tasks and test plan |
41
+ | Build | Was only the approved scope changed? | Diff and implementation notes |
42
+ | Verify | Does evidence support each acceptance criterion? | Executed checks and verification matrix |
43
+ | Review | Can another engineer challenge the result? | Independent review and findings |
44
+ | Deliver | Can this be released and operated safely? | Rollout, rollback, and observability plan |
45
+