verdicspec 0.0.0-stage → 0.2.1

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,19 @@
1
+ ---
2
+ name: bug-fix
3
+ description: Diagnose and fix a defect with a reproducible case, root-cause explanation, and regression protection.
4
+ ---
5
+
6
+ # Bug Fix
7
+
8
+ Compose `debugging`, `testing`, `observability` when needed, `code-review`, and `verification`.
9
+
10
+ Required outcomes:
11
+
12
+ - reproducible symptom or documented reproduction blocker;
13
+ - root cause or clearly bounded remaining hypotheses;
14
+ - smallest safe fix;
15
+ - regression test where practical;
16
+ - exact validation report.
17
+
18
+ Store the investigation and verification under `.verdicspec/reports/<change-id>-debugging.md` and `.verdicspec/reports/<change-id>-verification.md` when the host project uses the artifact contract.
19
+
@@ -0,0 +1,35 @@
1
+ ---
2
+ name: feature-development
3
+ description: Deliver a production software feature through specification, implementation, verification, and review.
4
+ ---
5
+
6
+ # Feature Development
7
+
8
+ First classify the work as greenfield, brownfield, or hybrid. For an existing product, use `brownfield-change`; for a new product, use `greenfield-product`. For a focused feature, use the sequence below.
9
+
10
+ 1. `project-discovery` and `technology-discovery`
11
+ 2. `specification` and `requirements`
12
+ 3. `architecture` when boundaries or design decisions are affected
13
+ 4. `planning`
14
+ 5. `testing`
15
+ 6. implementation using the selected technology pack
16
+ 7. `observability` when operational behavior is affected
17
+ 8. `verification`
18
+ 9. `code-review`, `release-readiness`, and `pull-request` as applicable
19
+
20
+ ## Gate conditions
21
+
22
+ - Do not implement while material requirements remain ambiguous.
23
+ - Do not choose a technology pack before `technology-discovery` has recorded evidence.
24
+ - Do not start implementation until the specification and plan are approved for the selected rigor level.
25
+ - Do not mark work complete without running relevant validation.
26
+ - Do not hide unrelated failures introduced or discovered during validation.
27
+ - Keep the final report tied to evidence from the repository and executed checks.
28
+
29
+ ## Required outputs
30
+
31
+ - specification;
32
+ - implementation plan;
33
+ - test plan;
34
+ - verification report;
35
+ - release-readiness report when the change is deliverable.
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: greenfield-product
3
+ description: Shape and deliver a new software product from problem discovery through the first validated vertical slice.
4
+ ---
5
+
6
+ # Greenfield Product
7
+
8
+ Compose `product-discovery`, `requirements`, `technology-discovery`, `architecture`, `planning`, `testing`, `observability`, `verification`, and `release-readiness` as needed.
9
+
10
+ ## Sequence
11
+
12
+ 1. Validate the problem, users, outcome, and non-goals.
13
+ 2. Define the smallest useful product slice.
14
+ 3. Record constraints, risks, and success measures.
15
+ 4. Choose architecture and technology from evidence and expected change.
16
+ 5. Build a vertical slice through the real boundaries.
17
+ 6. Verify behavior and operational readiness.
18
+ 7. Learn from feedback before expanding the product.
19
+
20
+ Do not create speculative infrastructure or broad abstractions before the first slice proves the important assumptions.
21
+
22
+ ## Outputs and gates
23
+
24
+ - Discovery: `.verdicspec/product-brief.md` approved.
25
+ - Baseline: `.verdicspec/technology-inventory.md` and `.verdicspec/system-context.md` available.
26
+ - Specification: requirements and acceptance criteria approved.
27
+ - Delivery: vertical slice verified with an explicit release decision.
28
+
@@ -0,0 +1,6 @@
1
+ # Verdicspec instructions
2
+
3
+ Follow the repository contract in [`AGENTS.md`](../AGENTS.md).
4
+
5
+ Before changing code, load the relevant skill from `skills/` and the matching technology pack from `technology-packs/` when applicable.
6
+
@@ -0,0 +1,40 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ validate:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - name: Checkout
16
+ uses: actions/checkout@v6
17
+
18
+ - name: Setup Node.js
19
+ uses: actions/setup-node@v6
20
+ with:
21
+ node-version: 24
22
+ cache: npm
23
+
24
+ - name: Install dependencies
25
+ run: npm ci
26
+
27
+ - name: Validate package
28
+ run: npm run validate
29
+
30
+ - name: Run CLI tests
31
+ run: npm test
32
+
33
+ - name: Test CLI help and package listing
34
+ run: |
35
+ node bin/verdicspec.mjs help
36
+ node bin/verdicspec.mjs list
37
+
38
+ - name: Check package contents
39
+ run: npm pack --dry-run
40
+
@@ -0,0 +1,32 @@
1
+ name: Manual npm publish
2
+
3
+ on:
4
+ workflow_dispatch:
5
+
6
+ permissions:
7
+ contents: read
8
+ id-token: write
9
+
10
+ jobs:
11
+ publish:
12
+ runs-on: ubuntu-latest
13
+ environment: npm
14
+ steps:
15
+ - name: Checkout
16
+ uses: actions/checkout@v6
17
+
18
+ - name: Setup Node.js
19
+ uses: actions/setup-node@v6
20
+ with:
21
+ node-version: 24
22
+ registry-url: https://registry.npmjs.org
23
+ package-manager-cache: false
24
+
25
+ - name: Install dependencies
26
+ run: npm ci
27
+
28
+ - name: Validate package
29
+ run: npm run validate
30
+
31
+ - name: Publish with npm trusted publishing
32
+ run: npm publish
@@ -0,0 +1,104 @@
1
+ name: Release on main
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ paths:
7
+ - 'AGENTS.md'
8
+ - 'CLAUDE.md'
9
+ - 'GEMINI.md'
10
+ - 'README.md'
11
+ - '.clinerules/**'
12
+ - '.cursor/**'
13
+ - '.github/copilot-instructions.md'
14
+ - '.verdicspec/**'
15
+ - 'bin/**'
16
+ - 'commands/**'
17
+ - 'docs/**'
18
+ - 'skills/**'
19
+ - 'technology-packs/**'
20
+ - 'templates/**'
21
+ - 'package.json'
22
+ - 'package-lock.json'
23
+
24
+ permissions:
25
+ contents: write
26
+
27
+ concurrency:
28
+ group: release-on-main
29
+ cancel-in-progress: false
30
+
31
+ jobs:
32
+ release:
33
+ if: github.actor != 'github-actions[bot]' && !contains(github.event.head_commit.message, '[skip release]')
34
+ runs-on: ubuntu-latest
35
+ environment: npm
36
+ steps:
37
+ - name: Checkout
38
+ uses: actions/checkout@v6
39
+ with:
40
+ fetch-depth: 0
41
+
42
+ - name: Setup Node.js
43
+ uses: actions/setup-node@v6
44
+ with:
45
+ node-version: 24
46
+ registry-url: https://registry.npmjs.org
47
+ package-manager-cache: false
48
+
49
+ - name: Install dependencies
50
+ run: npm ci
51
+
52
+ - name: Validate package
53
+ run: npm run validate
54
+
55
+ - name: Run tests
56
+ run: npm test
57
+
58
+ - name: Increment patch version
59
+ id: version
60
+ shell: bash
61
+ run: |
62
+ npm version patch --no-git-tag-version
63
+ VERSION="$(node -p "require('./package.json').version")"
64
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
65
+
66
+ - name: Publish package
67
+ env:
68
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
69
+ run: npm publish
70
+
71
+ - name: Create release commit and tag
72
+ env:
73
+ VERSION: ${{ steps.version.outputs.version }}
74
+ run: |
75
+ git config user.name "github-actions[bot]"
76
+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
77
+ git add package.json package-lock.json
78
+ git commit -m "chore(release): v${VERSION}"
79
+ git tag --annotate "v${VERSION}" --message "Release v${VERSION}"
80
+ git push origin HEAD:main
81
+ git push origin "v${VERSION}"
82
+
83
+ - name: Create GitHub Release
84
+ env:
85
+ GH_TOKEN: ${{ github.token }}
86
+ GH_REPOSITORY: ${{ github.repository }}
87
+ VERSION: ${{ steps.version.outputs.version }}
88
+ run: |
89
+ TAG="v${VERSION}"
90
+ for attempt in 1 2 3 4 5 6; do
91
+ if gh api "repos/${GH_REPOSITORY}/git/ref/tags/${TAG}" > /dev/null 2>&1; then
92
+ break
93
+ fi
94
+ if [ "$attempt" -eq 6 ]; then
95
+ echo "Tag ${TAG} was not visible through the GitHub API after pushing it."
96
+ exit 1
97
+ fi
98
+ sleep 2
99
+ done
100
+ gh api --method POST "repos/${GH_REPOSITORY}/releases" \
101
+ -f "tag_name=${TAG}" \
102
+ -f "target_commitish=${GITHUB_SHA}" \
103
+ -f "name=${TAG}" \
104
+ -F generate_release_notes=true
@@ -0,0 +1,13 @@
1
+ # Verdicspec project artifacts
2
+
3
+ This directory stores the durable artifacts produced by the Verdicspec for the host project.
4
+
5
+ - `product-brief.md`: product problem, users, outcome, and smallest useful slice.
6
+ - `system-context.md`: current system, boundaries, dependencies, and invariants.
7
+ - `technology-inventory.md`: detected technology and confirmed commands.
8
+ - `specifications/`: approved change specifications.
9
+ - `decisions/`: architecture and product decisions.
10
+ - `plans/`: implementation plans.
11
+ - `reports/`: verification, spike, review, and release reports.
12
+
13
+ Artifacts are evidence and decision records. They should evolve with the product and must not claim checks that were not executed.
@@ -0,0 +1,17 @@
1
+ {
2
+ "method": "verdicspec",
3
+ "version": "0.2",
4
+ "projectMode": "auto",
5
+ "rigor": "adaptive",
6
+ "technologyDiscovery": "required",
7
+ "artifacts": {
8
+ "root": ".verdicspec",
9
+ "productBrief": ".verdicspec/product-brief.md",
10
+ "systemContext": ".verdicspec/system-context.md",
11
+ "technologyInventory": ".verdicspec/technology-inventory.md",
12
+ "specifications": ".verdicspec/specifications",
13
+ "decisions": ".verdicspec/decisions",
14
+ "plans": ".verdicspec/plans",
15
+ "reports": ".verdicspec/reports"
16
+ }
17
+ }
package/AGENTS.md ADDED
@@ -0,0 +1,60 @@
1
+ # Verdicspec
2
+
3
+ Portable specification-driven engineering method for AI coding agents.
4
+
5
+ Repository: https://github.com/luismpenholato/verdicspec
6
+ Package: `npm i -g verdicspec`
7
+
8
+ ## Auto-routing (user does not need to name an agent)
9
+
10
+ Choose agent/skill by intent. Do not ask “should I use agent X?” — just use it.
11
+
12
+ | Intent | Agent | Primary skill |
13
+ |--------|-------|---------------|
14
+ | Explore / map / discover | `explorer` | `skills/core/project-discovery` |
15
+ | Specify feature/behavior | `specifier` | `skills/core/specification` |
16
+ | Plan tasks | `planner` | `skills/core/planning` |
17
+ | Architecture | `architect` | `skills/core/architecture` |
18
+ | Bug / failure | `debugger` | `skills/core/debugging` |
19
+ | Technical spike | `spike-engineer` | `skills/core/spike` |
20
+ | Implement after approval | `implementer` | `skills/workflows/feature-development` |
21
+ | Tests | `tester` | `skills/practices/testing` |
22
+ | Done? / final gate | `verifier` | `skills/practices/verification` |
23
+ | Security | `security-reviewer` | `skills/practices/security` |
24
+ | Observability | `observability-engineer` | `skills/practices/observability` |
25
+ | Code review | `reviewer` | `skills/practices/code-review` |
26
+ | Create PR | `pr-creator` | `skills/practices/pull-request` |
27
+ | Release readiness | `releaser` | `skills/practices/release-readiness` |
28
+
29
+ ## Where each tool reads config
30
+
31
+ | Tool | Rules | Agents | Skills |
32
+ |------|-------|--------|--------|
33
+ | Cursor | `.cursor/rules/` | `.cursor/agents/` | `.cursor/skills/` or `skills/` |
34
+ | Claude Code | `CLAUDE.md` + `.claude/rules/` | `.claude/agents/` | `.claude/skills/` |
35
+ | Codex | this `AGENTS.md` | `.agents/agents/` | `.agents/skills/` or `skills/` |
36
+ | Antigravity | `.agents/rules/` + this file | `.agents/agents/` | `.agents/skills/` |
37
+
38
+ Canonical skills: `skills/**/SKILL.md`. Canonical agents: `agents/*.md` (mirrored into tool folders).
39
+
40
+ ## Repository contract
41
+
42
+ - Read the relevant skill before executing a workflow.
43
+ - Start with `technology-discovery` when stack/runtime/commands are unknown.
44
+ - Classify work as greenfield, brownfield, or hybrid before choosing a workflow.
45
+ - Select rigor L0–L3 from `docs/workflow.md`.
46
+ - Keep the core technology-agnostic; stack specifics live in `technology-packs/`.
47
+ - Use `.verdicspec/` as the durable artifact root (`docs/artifact-contract.md`).
48
+ - Every implementation needs an explicit verification outcome.
49
+ - Never claim a command/test/review/deploy was performed unless it was.
50
+ - Do not modernize stack/patterns without an explicit user request.
51
+ - Do not create commits unless explicitly requested.
52
+
53
+ ## Skill discovery
54
+
55
+ - `skills/core/` — reasoning and lifecycle
56
+ - `skills/practices/` — testing, observability, review, delivery
57
+ - `skills/workflows/` — end-to-end modes
58
+ - `technology-packs/` — Node.js, .NET, Python, Java
59
+ - `commands/` — tool-independent command entry points
60
+ - `.verdicspec/` — host-project config and artifacts
package/CLAUDE.md ADDED
@@ -0,0 +1,10 @@
1
+ # Verdicspec — Claude Code
2
+
3
+ Follow [AGENTS.md](AGENTS.md) and .claude/rules/.
4
+
5
+ - Agents: .claude/agents/
6
+ - Skills: .claude/skills/ (canonical source remains skills/)
7
+ - Artifacts: .verdicspec/
8
+
9
+ Choose agent/skill by intent — the user does not need to name them.
10
+ Load only the skill relevant to the current task.
package/GEMINI.md ADDED
@@ -0,0 +1,6 @@
1
+ # Verdicspec
2
+
3
+ Read and follow the repository contract in [AGENTS.md](AGENTS.md).
4
+
5
+ Canonical skills are under skills/. Named agents are under gents/ (also mirrored for Cursor/Claude/Codex/Antigravity).
6
+ Load only the skill relevant to the current task.
package/README.md CHANGED
@@ -1,3 +1,112 @@
1
- # Temporary Holding Version
1
+ # Verdicspec
2
+
3
+ [![CI](https://github.com/luismpenholato/verdicspec/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/luismpenholato/verdicspec/actions/workflows/ci.yml)
4
+ [![GitHub release](https://img.shields.io/github/v/release/luismpenholato/verdicspec?display_name=tag&sort=semver)](https://github.com/luismpenholato/verdicspec/releases)
5
+ [![npm version](https://img.shields.io/npm/v/verdicspec.svg)](https://www.npmjs.com/package/verdicspec)
6
+ [![License](https://img.shields.io/npm/l/verdicspec.svg)](https://opensource.org/license/mit/)
7
+
8
+ ## Modular engineering for AI-assisted software development
9
+
10
+ Install the latest published package from [npm](https://www.npmjs.com/package/verdicspec):
11
+
12
+ ```powershell
13
+ npm install --global verdicspec
14
+ ```
15
+
16
+ Then install the method into a project:
17
+
18
+ ```powershell
19
+ verdicspec init . --tool all
20
+ ```
21
+
22
+ Verdicspec is a technology-agnostic engineering method for building reliable software with AI agents.
23
+
24
+ It combines specification-driven development with disciplined implementation, testing, observability, debugging, review, and verifiable delivery evidence.
25
+
26
+ ## Principles
27
+
28
+ - Understand the problem before changing the code.
29
+ - Treat specifications and acceptance criteria as shared contracts.
30
+ - Prefer the smallest safe change that satisfies the contract.
31
+ - Make tests, observability, and review part of implementation—not afterthoughts.
32
+ - Report evidence separately from assumptions.
33
+ - Keep the core generic and move technology-specific knowledge into focused skills.
34
+
35
+ ## Repository structure
36
+
37
+ ```text
38
+ agents/ # Named agents (mirrored for Cursor/Claude/Codex/Antigravity)
39
+ skills/
40
+ ├── core/ # Technology-agnostic engineering capabilities
41
+ ├── practices/ # Reusable engineering practices
42
+ ├── technology-packs/ # Node.js, .NET, Python, and other stacks
43
+ └── workflows/ # Composable end-to-end work modes
44
+ commands/ # Tool-independent command entry points
45
+ templates/ # Specifications, plans, tests, reviews, and reports
46
+ docs/ # Method documentation and design decisions
47
+ .verdicspec/ # Method artifacts root
48
+ ```
49
+
50
+ ## Initial skills
51
+
52
+ - `core/specification`: define intent, behavior, constraints, and acceptance criteria.
53
+ - `core/debugging`: reproduce failures, test hypotheses, identify root cause, and prevent regression.
54
+ - `core/spike`: answer technical questions through bounded experiments and recorded evidence.
55
+ - `core/architecture`: make proportionate architecture decisions.
56
+ - `core/project-discovery`: establish a baseline for greenfield, brownfield, and hybrid projects.
57
+ - `core/technology-discovery`: detect the real stack and select applicable technology packs.
58
+ - `core/product-discovery`: frame new product problems and the smallest useful slice.
59
+ - `core/requirements`: structure functional and non-functional requirements.
60
+ - `core/planning`: create ordered, verifiable implementation tasks.
61
+ - `practices/testing`: design tests from behavior and preserve regression coverage.
62
+ - `practices/observability`: define useful logs, metrics, traces, and operational signals.
63
+ - `practices/code-review`: review correctness, risk, security, and maintainability.
64
+ - `practices/pull-request`: prepare focused, evidence-based pull requests.
65
+ - `practices/verification`: map acceptance criteria to executed evidence.
66
+ - `practices/security`: analyze security, privacy, abuse, and supply-chain risks.
67
+ - `practices/data-migration`: plan safe schema and data changes.
68
+ - `practices/release-readiness`: decide whether a change can be delivered safely.
69
+ - `workflows/feature-development`: compose the core loop for a production change.
70
+ - `workflows/bug-fix`: diagnose and fix defects with regression protection.
71
+ - `workflows/greenfield-product`: create a new product through a validated vertical slice.
72
+ - `workflows/brownfield-change`: safely change an existing product.
73
+
74
+ ## Portability
75
+
76
+ The method uses a canonical `AGENTS.md`, portable `SKILL.md` files, tool-independent commands, and thin adapters for Cursor, Claude Code, Codex, Antigravity, GitHub Copilot, Gemini CLI, and Cline. Run `scripts/install.ps1` from PowerShell to install the method into another project without overwriting existing files unless `-Force` is supplied.
77
+
78
+ The canonical structure is independent of a model provider, editor, CLI, or programming language. Technology packs provide focused guidance for Node.js, .NET, Python, and Java.
79
+
80
+ Validate the repository and installer with:
81
+
82
+ ```powershell
83
+ .\scripts\validate.ps1 -TestInstaller
84
+ ```
85
+
86
+ See [tool support](docs/tool-support.md) for the distinction between GPT as a model and Codex as the coding-agent environment.
87
+
88
+ ## npm CLI
89
+
90
+ When published, the recommended installation will be:
91
+
92
+ ```powershell
93
+ npm install -g verdicspec
94
+ verdicspec init . --tool all
95
+ ```
96
+
97
+ Available commands:
98
+
99
+ ```text
100
+ verdicspec init [directory] Install the method in a project
101
+ verdicspec validate Validate the packaged skills and required files
102
+ verdicspec list List commands and skills
103
+ verdicspec doctor [directory] Check whether a project is installed correctly
104
+ verdicspec inspect [directory] Detect technology evidence and write the inventory
105
+ ```
106
+
107
+ The npm CI/CD setup is documented in [docs/npm-release.md](docs/npm-release.md). Pull requests run validation automatically, and package changes merged into `main` create a patch release, npm publication, version tag, and GitHub Release.
108
+
109
+ ## Status
110
+
111
+ Early development. The method and skill contracts are expected to evolve before the first stable release.
2
112
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: architect
3
+ description: Toma decisoes de arquitetura proporcionais ao risco. Use proativamente em mudancas cross-cutting ou L2/L3.
4
+ ---
5
+
6
+ Voce e o agent `architect` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/core/architecture/SKILL.md`.
10
+ 2. Registre trade-offs e decisoes.
11
+ 3. Prefira o menor desenho que satisfaz o contrato.
12
+ 4. Nao modernize stack sem pedido explicito.
@@ -0,0 +1,13 @@
1
+ ---
2
+ name: debugger
3
+ description: Investiga falhas com reproducao, hipoteses e evidencia. Use proativamente em bug, regressao ou falha de teste/build.
4
+ ---
5
+
6
+ Voce e o agent `debugger` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/core/debugging/SKILL.md`.
10
+ 2. Se aplicavel, leia tambem `skills/workflows/bug-fix/SKILL.md`.
11
+ 3. Nao corrija sem causa raiz.
12
+ 4. Reproduza, forme hipotese minima, valide, so entao corrija.
13
+ 5. Adicione protecao de regressao.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: explorer
3
+ description: Explora produto, codebase e impacto sem implementar. Use proativamente para descobrir contexto, mapear brownfield ou esclarecer escopo.
4
+ ---
5
+
6
+ Voce e o agent `explorer` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/core/project-discovery/SKILL.md`.
10
+ 2. Se aplicavel, leia tambem `skills/core/brownfield-analysis/SKILL.md`.
11
+ 3. Se aplicavel, leia tambem `skills/core/product-discovery/SKILL.md`.
12
+ 4. Se aplicavel, leia tambem `skills/core/technology-discovery/SKILL.md`.
13
+ 5. Classifique greenfield/brownfield/hybrid.
14
+ 6. Descubra a stack real com technology-discovery.
15
+ 7. Mapeie riscos e seams seguros.
16
+ 8. Nao implemente codigo nesta etapa.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: implementer
3
+ description: Implementa mudanca aprovada seguindo o plano e o padrao do repositorio. Use proativamente apos plan/aprovacao.
4
+ ---
5
+
6
+ Voce e o agent `implementer` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/workflows/feature-development/SKILL.md`.
10
+ 2. Se aplicavel, leia tambem `skills/workflows/brownfield-change/SKILL.md`.
11
+ 3. Clone o padrao do arquivo/dominio vizinho.
12
+ 4. Menor mudanca segura que satisfaz o contrato.
13
+ 5. Nao faca refatoracao oportunista.
14
+ 6. Termine com verification.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: observability-engineer
3
+ description: Define logs, metricas e traces uteis. Use proativamente em features operacionais.
4
+ ---
5
+
6
+ Voce e o agent `observability-engineer` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/practices/observability/SKILL.md`.
10
+ 2. Sinais diagnosticos sem secrets.
11
+ 3. Reutilize padroes do projeto.
@@ -0,0 +1,12 @@
1
+ ---
2
+ name: planner
3
+ description: Converte especificacao aprovada em tasks ordenadas e verificaveis. Use proativamente apos specify/aprovacao.
4
+ ---
5
+
6
+ Voce e o agent `planner` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/core/planning/SKILL.md`.
10
+ 2. Quebre o trabalho em tasks pequenas e verificaveis.
11
+ 3. Vincule cada task a criterio de aceite.
12
+ 4. Nao implemente codigo nesta etapa.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: pr-creator
3
+ description: Prepara Pull Request focada e com evidencia. Use proativamente quando o usuario pedir PR.
4
+ ---
5
+
6
+ Voce e o agent `pr-creator` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/practices/pull-request/SKILL.md`.
10
+ 2. Escopo claro, evidencia, riscos.
11
+ 3. Nao faca push/PR sem autorizacao explicita.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: releaser
3
+ description: Avalia se a mudanca pode ser entregue com seguranca. Use proativamente antes de release.
4
+ ---
5
+
6
+ Voce e o agent `releaser` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/practices/release-readiness/SKILL.md`.
10
+ 2. Rollout, rollback, migracao e evidencia operacional.
11
+ 3. Nao recomende release sem gates satisfeitos.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: reviewer
3
+ description: Revisa corretude, risco, seguranca e manutencao. Use proativamente antes de merge.
4
+ ---
5
+
6
+ Voce e o agent `reviewer` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/practices/code-review/SKILL.md`.
10
+ 2. Revise diff contra spec e riscos.
11
+ 3. Exija evidencia de verificacao.
@@ -0,0 +1,11 @@
1
+ ---
2
+ name: security-reviewer
3
+ description: Revisa riscos de seguranca, privacidade e supply-chain. Use proativamente em mudancas sensiveis.
4
+ ---
5
+
6
+ Voce e o agent `security-reviewer` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/practices/security/SKILL.md`.
10
+ 2. Bloqueie secrets e acesso indevido.
11
+ 3. Registre riscos e mitigacoes.
@@ -0,0 +1,14 @@
1
+ ---
2
+ name: specifier
3
+ description: Cria ou refina especificacao testavel antes de codar. Use proativamente em feature nova ou mudanca de comportamento.
4
+ ---
5
+
6
+ Voce e o agent `specifier` do Verdicspec.
7
+
8
+ Quando invocado:
9
+ 1. Leia e siga `skills/core/specification/SKILL.md`.
10
+ 2. Se aplicavel, leia tambem `skills/core/requirements/SKILL.md`.
11
+ 3. Defina intent, comportamento, constraints e acceptance criteria.
12
+ 4. Use templates/feature-spec.md quando aplicavel.
13
+ 5. Nao implemente codigo nesta etapa.
14
+ 6. Peca aprovacao quando a mudanca for media/grande.
@@ -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.