@jeancodogno/specforce-kit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (153) hide show
  1. package/.geminiignore +15 -0
  2. package/.github/workflows/ci.yml +100 -0
  3. package/.github/workflows/release.yml +51 -0
  4. package/.golangci.yml +21 -0
  5. package/.goreleaser.yaml +43 -0
  6. package/.rgignore +13 -0
  7. package/.specforce/config.yaml +32 -0
  8. package/.specforce/docs/.gitkeep +0 -0
  9. package/.specforce/docs/architecture.md +98 -0
  10. package/.specforce/docs/engineering.md +80 -0
  11. package/.specforce/docs/governance.md +30 -0
  12. package/.specforce/docs/memorial.md +44 -0
  13. package/.specforce/docs/principles.md +31 -0
  14. package/.specforce/docs/security.md +31 -0
  15. package/.specforce/docs/ui-ux.md +129 -0
  16. package/.specforce/specs/.gitkeep +0 -0
  17. package/AGENTS.md +36 -0
  18. package/CONTRIBUTING.md +81 -0
  19. package/LICENSE +21 -0
  20. package/Makefile +49 -0
  21. package/README.md +144 -0
  22. package/assets/logo-header.png +0 -0
  23. package/assets/logo.png +0 -0
  24. package/docs/artifacts.md +41 -0
  25. package/docs/cli.md +73 -0
  26. package/docs/configuration.md +50 -0
  27. package/docs/getting-started.md +110 -0
  28. package/docs/supported-tools.md +14 -0
  29. package/go.mod +35 -0
  30. package/go.sum +61 -0
  31. package/index.js +0 -0
  32. package/package.json +26 -0
  33. package/src/cmd/specforce/main.go +23 -0
  34. package/src/cmd/specforce/main_test.go +7 -0
  35. package/src/internal/agent/artifacts/constitution/architecture.yaml +70 -0
  36. package/src/internal/agent/artifacts/constitution/engineering.yaml +52 -0
  37. package/src/internal/agent/artifacts/constitution/governance.yaml +41 -0
  38. package/src/internal/agent/artifacts/constitution/memorial.yaml +55 -0
  39. package/src/internal/agent/artifacts/constitution/principles.yaml +54 -0
  40. package/src/internal/agent/artifacts/constitution/security.yaml +47 -0
  41. package/src/internal/agent/artifacts/constitution/ui-ux.yaml +158 -0
  42. package/src/internal/agent/artifacts/spec/design.yaml +50 -0
  43. package/src/internal/agent/artifacts/spec/requirements.yaml +48 -0
  44. package/src/internal/agent/artifacts/spec/tasks.yaml +55 -0
  45. package/src/internal/agent/compatibility_test.go +120 -0
  46. package/src/internal/agent/cwd_test.go +9 -0
  47. package/src/internal/agent/embed.go +19 -0
  48. package/src/internal/agent/integration_test.go +138 -0
  49. package/src/internal/agent/kit/agents/product-analyst.yaml +31 -0
  50. package/src/internal/agent/kit/agents/technical-developer.yaml +28 -0
  51. package/src/internal/agent/kit/agents/technical-project-planner.yaml +30 -0
  52. package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +36 -0
  53. package/src/internal/agent/kit/agents/technical-solution-architect.yaml +32 -0
  54. package/src/internal/agent/kit/commands/archive.yaml +25 -0
  55. package/src/internal/agent/kit/commands/constitution.yaml +132 -0
  56. package/src/internal/agent/kit/commands/implement.yaml +96 -0
  57. package/src/internal/agent/kit/commands/spec.yaml +94 -0
  58. package/src/internal/agent/kit/instructions/archive.md +68 -0
  59. package/src/internal/agent/kit/kit.yaml +111 -0
  60. package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +56 -0
  61. package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +58 -0
  62. package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +38 -0
  63. package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +52 -0
  64. package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +137 -0
  65. package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +103 -0
  66. package/src/internal/agent/kit_manifests_test.go +58 -0
  67. package/src/internal/agent/manifest.go +15 -0
  68. package/src/internal/agent/registry.go +69 -0
  69. package/src/internal/agent/registry_test.go +51 -0
  70. package/src/internal/agent/translator.go +334 -0
  71. package/src/internal/agent/translator_test.go +734 -0
  72. package/src/internal/cli/archive.go +91 -0
  73. package/src/internal/cli/archive_test.go +67 -0
  74. package/src/internal/cli/cli.go +259 -0
  75. package/src/internal/cli/cli_test.go +130 -0
  76. package/src/internal/cli/cobra/archive.go +26 -0
  77. package/src/internal/cli/cobra/console.go +21 -0
  78. package/src/internal/cli/cobra/constitution.go +44 -0
  79. package/src/internal/cli/cobra/dummy_test.go +7 -0
  80. package/src/internal/cli/cobra/implementation.go +50 -0
  81. package/src/internal/cli/cobra/init.go +23 -0
  82. package/src/internal/cli/cobra/install.go +21 -0
  83. package/src/internal/cli/cobra/root.go +47 -0
  84. package/src/internal/cli/cobra/spec.go +91 -0
  85. package/src/internal/cli/console.go +48 -0
  86. package/src/internal/cli/constitution.go +190 -0
  87. package/src/internal/cli/constitution_test.go +50 -0
  88. package/src/internal/cli/implementation.go +153 -0
  89. package/src/internal/cli/implementation_test.go +165 -0
  90. package/src/internal/cli/spec.go +369 -0
  91. package/src/internal/cli/spec_test.go +85 -0
  92. package/src/internal/constitution/registry.go +139 -0
  93. package/src/internal/constitution/registry_test.go +97 -0
  94. package/src/internal/constitution/status.go +70 -0
  95. package/src/internal/constitution/status_test.go +160 -0
  96. package/src/internal/core/blueprint.go +49 -0
  97. package/src/internal/core/blueprint_test.go +58 -0
  98. package/src/internal/core/config.go +124 -0
  99. package/src/internal/core/config_test.go +145 -0
  100. package/src/internal/core/constants.go +13 -0
  101. package/src/internal/core/errors.go +31 -0
  102. package/src/internal/core/errors_test.go +48 -0
  103. package/src/internal/core/hooks.go +89 -0
  104. package/src/internal/core/hooks_test.go +51 -0
  105. package/src/internal/core/kit.go +15 -0
  106. package/src/internal/core/kit_test.go +65 -0
  107. package/src/internal/core/path.go +115 -0
  108. package/src/internal/core/path_test.go +101 -0
  109. package/src/internal/core/ui.go +19 -0
  110. package/src/internal/installer/dependencies.go +23 -0
  111. package/src/internal/installer/install.go +89 -0
  112. package/src/internal/installer/installer.go +45 -0
  113. package/src/internal/installer/installer_test.go +96 -0
  114. package/src/internal/project/agents_md.go +108 -0
  115. package/src/internal/project/agents_md_test.go +101 -0
  116. package/src/internal/project/bootstrapper.go +64 -0
  117. package/src/internal/project/bootstrapper_test.go +89 -0
  118. package/src/internal/project/detector.go +35 -0
  119. package/src/internal/project/detector_test.go +96 -0
  120. package/src/internal/project/refresh_integration_test.go +86 -0
  121. package/src/internal/project/service.go +93 -0
  122. package/src/internal/project/service_test.go +135 -0
  123. package/src/internal/spec/archive.go +49 -0
  124. package/src/internal/spec/archive_test.go +55 -0
  125. package/src/internal/spec/discovery.go +53 -0
  126. package/src/internal/spec/discovery_test.go +60 -0
  127. package/src/internal/spec/implementation.go +296 -0
  128. package/src/internal/spec/implementation_test.go +253 -0
  129. package/src/internal/spec/registry.go +142 -0
  130. package/src/internal/spec/registry_test.go +105 -0
  131. package/src/internal/spec/scanner.go +219 -0
  132. package/src/internal/spec/scanner_test.go +243 -0
  133. package/src/internal/spec/service.go +157 -0
  134. package/src/internal/spec/service_test.go +238 -0
  135. package/src/internal/spec/status.go +94 -0
  136. package/src/internal/spec/status_test.go +146 -0
  137. package/src/internal/spec/tasks.go +103 -0
  138. package/src/internal/spec/tasks_test.go +137 -0
  139. package/src/internal/tui/components.go +132 -0
  140. package/src/internal/tui/console.go +247 -0
  141. package/src/internal/tui/console_test.go +19 -0
  142. package/src/internal/tui/constitution.go +36 -0
  143. package/src/internal/tui/constitution_test.go +32 -0
  144. package/src/internal/tui/implementation.go +151 -0
  145. package/src/internal/tui/logo.go +89 -0
  146. package/src/internal/tui/multiselect.go +199 -0
  147. package/src/internal/tui/progressbar.go +37 -0
  148. package/src/internal/tui/progressbar_test.go +30 -0
  149. package/src/internal/tui/spec.go +35 -0
  150. package/src/internal/tui/spinner.go +66 -0
  151. package/src/internal/tui/terminal.go +18 -0
  152. package/src/internal/tui/theme.go +125 -0
  153. package/src/internal/tui/ui.go +52 -0
@@ -0,0 +1,110 @@
1
+ # Getting Started with Specforce Kit
2
+
3
+ Welcome to the **Specforce Kit**! This guide will help you set up your environment and take your first steps with Spec-Driven Development (SDD).
4
+
5
+ ## Prerequisites
6
+
7
+ - Node.js and NPM (for the recommended installation)
8
+ - Go 1.26+ and Make (if you wish to build from source)
9
+ - Your favorite AI agent (Gemini CLI, Claude Code, KiloCode, etc.)
10
+
11
+ ## Installation
12
+
13
+ The easiest way to install Specforce Kit is globally via NPM:
14
+
15
+ ```bash
16
+ npm install -g @specforce/kit
17
+ ```
18
+
19
+ If you prefer to install from source:
20
+
21
+ ```bash
22
+ git clone https://github.com/jeancodogno/specforce-kit.git
23
+ cd specforce-kit
24
+ make build
25
+ make install
26
+ ```
27
+
28
+ ## First Steps
29
+
30
+ ### 1. Initialize your Project
31
+
32
+ Navigate to your project directory (new or existing) and initialize Specforce:
33
+
34
+ ```bash
35
+ specforce init
36
+ ```
37
+
38
+ This command will prepare the necessary structure, setting up the state folders (`.specforce/`) and base files for your AI agent.
39
+
40
+ ### 2. Define the Constitution
41
+
42
+ The **Constitution** is the foundational set of rules for your project (architecture, UI/UX, security). Instead of polluting your agent's context with dozens of loose rules, Specforce centralizes this in a structured way.
43
+
44
+ In your terminal, start your AI agent (e.g., `gemini`) and run:
45
+
46
+ ```text
47
+ /spf:constitution {your project description and tech stack}
48
+ ```
49
+
50
+ The agent will ask a few questions to align the project and will create the foundational documents in the `docs/` folder.
51
+
52
+ ### 3. Create your First Specification
53
+
54
+ Every code change in Specforce requires a specification. To add a new feature, ask your agent:
55
+
56
+ ```text
57
+ /spf:spec {describe the feature you want to build}
58
+ ```
59
+
60
+ The agent will create the essential artifacts: `requirements.md`, `design.md`, and `tasks.md`.
61
+
62
+ ---
63
+
64
+ ## Workflow: The 4-Step Lifecycle
65
+
66
+ The Specforce Kit workflow is based on **Spec-Driven Development (SDD)**. In the age of AI, implementation has become a commodity, but architectural design without validation is a major risk.
67
+
68
+ SDD separates **design** from **implementation**, ensuring that no code is generated on the fly ("vibe coding") without a formal contract.
69
+
70
+ The development cycle with AI agents in Specforce follows a deterministic path:
71
+
72
+ ### 1. Foundation: The Constitution (`/spf:constitution`)
73
+ Everything starts with the **Constitution**. Before writing any code, the project needs clear rules on Architecture, UI/UX, and Security.
74
+ - The agent interacts with you to understand the project's scope.
75
+ - It documents these decisions, which will serve as immutable "laws" for all future implementations.
76
+ - **Advantage:** The agent only loads the segments of the constitution it needs, saving tokens and preventing hallucinations.
77
+
78
+ ### 2. The Contract: The Specification (`/spf:spec`)
79
+ Every new feature, fix, or refactor starts here.
80
+ - You explain what you need. The agent translates your needs into 3 artifacts:
81
+ - **Requirements** (the "what")
82
+ - **Design** (the "how", architecturally)
83
+ - **Tasks** (the atomic execution roadmap)
84
+ - *Human Action:* You must review and approve this specification. This is your contract with the machine.
85
+
86
+ ### 3. Execution: The Implementation (`/spf:implement`)
87
+ With the approved specification, the agent enters execution mode.
88
+ - The agent strictly follows the task list generated in the previous step.
89
+ - Internal tools, such as [Validation Hooks](configuration.md), ensure the agent doesn't skip tests, linters, or security steps before marking a task as "finished".
90
+ - *Human Action:* Use the `specforce console` command in another terminal to monitor the agent's progress in real-time.
91
+
92
+ ### 4. Closure: Archiving (`/spf:archive`)
93
+ After the feature is fully coded and tested, the specification needs to be closed.
94
+ - The agent archives the completed specification to keep the environment clean.
95
+ - It follows standardized **Archiving Instructions** to analyze what was done and update the Global Constitution (and the project Memorial) if new systemic architectural decisions have emerged.
96
+ - You can customize these rules in `config.yaml` to include steps like updating external trackers or specific cleanup tasks.
97
+
98
+ ---
99
+
100
+ ## Human Role vs. Machine Role
101
+
102
+ In Specforce, roles are clear:
103
+
104
+ - **The Human Architect (Governance):** Sets the project's direction, approves specifications, and ensures the system as a whole makes business sense.
105
+ - **The AI Agent (Executor):** Executes the approved roadmap, generating high-quality code, tests, and internal documentation efficiently and rapidly, always respecting the Constitution.
106
+
107
+ ---
108
+
109
+ To explore the terminal commands, see the [CLI Reference](cli.md).
110
+ Learn more about the documents generated in this process on the [Artifacts](artifacts.md) page.
@@ -0,0 +1,14 @@
1
+ # Supported AI Agents and Tools
2
+
3
+ Specforce is designed to be independent of any specific tool or ecosystem (tool-agnostic). However, we offer native *Slash Commands* integration out-of-the-box for the most popular AI coding assistants:
4
+
5
+ - **Gemini CLI** (Google)
6
+ - **Claude Code** (Anthropic)
7
+ - **Qwen** (Alibaba)
8
+ - **Kimi Code** (Moonshot AI)
9
+ - **OpenCode**
10
+ - **KiloCode**
11
+ - **Codex**
12
+ - **Antigravity**
13
+
14
+ *Can't find your favorite agent? Submit a PR creating a Kit for it!*
package/go.mod ADDED
@@ -0,0 +1,35 @@
1
+ module github.com/jeancodogno/specforce-kit
2
+
3
+ go 1.25.0
4
+
5
+ require (
6
+ github.com/charmbracelet/bubbles v1.0.0
7
+ github.com/charmbracelet/bubbletea v1.3.10
8
+ github.com/charmbracelet/lipgloss v1.1.0
9
+ github.com/mattn/go-isatty v0.0.21
10
+ github.com/spf13/cobra v1.10.2
11
+ golang.org/x/text v0.36.0
12
+ gopkg.in/yaml.v3 v3.0.1
13
+ )
14
+
15
+ require (
16
+ github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
17
+ github.com/charmbracelet/colorprofile v0.4.3 // indirect
18
+ github.com/charmbracelet/x/ansi v0.11.7 // indirect
19
+ github.com/charmbracelet/x/cellbuf v0.0.15 // indirect
20
+ github.com/charmbracelet/x/term v0.2.2 // indirect
21
+ github.com/clipperhouse/displaywidth v0.11.0 // indirect
22
+ github.com/clipperhouse/uax29/v2 v2.7.0 // indirect
23
+ github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
24
+ github.com/inconshreveable/mousetrap v1.1.0 // indirect
25
+ github.com/lucasb-eyer/go-colorful v1.4.0 // indirect
26
+ github.com/mattn/go-localereader v0.0.1 // indirect
27
+ github.com/mattn/go-runewidth v0.0.23 // indirect
28
+ github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
29
+ github.com/muesli/cancelreader v0.2.2 // indirect
30
+ github.com/muesli/termenv v0.16.0 // indirect
31
+ github.com/rivo/uniseg v0.4.7 // indirect
32
+ github.com/spf13/pflag v1.0.10 // indirect
33
+ github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
34
+ golang.org/x/sys v0.43.0 // indirect
35
+ )
package/go.sum ADDED
@@ -0,0 +1,61 @@
1
+ github.com/aymanbagabas/go-osc52/v2 v2.0.1 h1:HwpRHbFMcZLEVr42D4p7XBqjyuxQH5SMiErDT4WkJ2k=
2
+ github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ2ASbcXHWsFqH8hp8=
3
+ github.com/charmbracelet/bubbles v1.0.0 h1:12J8/ak/uCZEMQ6KU7pcfwceyjLlWsDLAxB5fXonfvc=
4
+ github.com/charmbracelet/bubbles v1.0.0/go.mod h1:9d/Zd5GdnauMI5ivUIVisuEm3ave1XwXtD1ckyV6r3E=
5
+ github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
6
+ github.com/charmbracelet/bubbletea v1.3.10/go.mod h1:ORQfo0fk8U+po9VaNvnV95UPWA1BitP1E0N6xJPlHr4=
7
+ github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
8
+ github.com/charmbracelet/colorprofile v0.4.3/go.mod h1:/zT4BhpD5aGFpqQQqw7a+VtHCzu+zrQtt1zhMt9mR4Q=
9
+ github.com/charmbracelet/lipgloss v1.1.0 h1:vYXsiLHVkK7fp74RkV7b2kq9+zDLoEU4MZoFqR/noCY=
10
+ github.com/charmbracelet/lipgloss v1.1.0/go.mod h1:/6Q8FR2o+kj8rz4Dq0zQc3vYf7X+B0binUUBwA0aL30=
11
+ github.com/charmbracelet/x/ansi v0.11.7 h1:kzv1kJvjg2S3r9KHo8hDdHFQLEqn4RBCb39dAYC84jI=
12
+ github.com/charmbracelet/x/ansi v0.11.7/go.mod h1:9qGpnAVYz+8ACONkZBUWPtL7lulP9No6p1epAihUZwQ=
13
+ github.com/charmbracelet/x/cellbuf v0.0.15 h1:ur3pZy0o6z/R7EylET877CBxaiE1Sp1GMxoFPAIztPI=
14
+ github.com/charmbracelet/x/cellbuf v0.0.15/go.mod h1:J1YVbR7MUuEGIFPCaaZ96KDl5NoS0DAWkskup+mOY+Q=
15
+ github.com/charmbracelet/x/term v0.2.2 h1:xVRT/S2ZcKdhhOuSP4t5cLi5o+JxklsoEObBSgfgZRk=
16
+ github.com/charmbracelet/x/term v0.2.2/go.mod h1:kF8CY5RddLWrsgVwpw4kAa6TESp6EB5y3uxGLeCqzAI=
17
+ github.com/clipperhouse/displaywidth v0.11.0 h1:lBc6kY44VFw+TDx4I8opi/EtL9m20WSEFgwIwO+UVM8=
18
+ github.com/clipperhouse/displaywidth v0.11.0/go.mod h1:bkrFNkf81G8HyVqmKGxsPufD3JhNl3dSqnGhOoSD/o0=
19
+ github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJv2v7Vk=
20
+ github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
21
+ github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
22
+ github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
23
+ github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
24
+ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
25
+ github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
26
+ github.com/lucasb-eyer/go-colorful v1.4.0 h1:UtrWVfLdarDgc44HcS7pYloGHJUjHV/4FwW4TvVgFr4=
27
+ github.com/lucasb-eyer/go-colorful v1.4.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
28
+ github.com/mattn/go-isatty v0.0.21 h1:xYae+lCNBP7QuW4PUnNG61ffM4hVIfm+zUzDuSzYLGs=
29
+ github.com/mattn/go-isatty v0.0.21/go.mod h1:ZXfXG4SQHsB/w3ZeOYbR0PrPwLy+n6xiMrJlRFqopa4=
30
+ github.com/mattn/go-localereader v0.0.1 h1:ygSAOl7ZXTx4RdPYinUpg6W99U8jWvWi9Ye2JC/oIi4=
31
+ github.com/mattn/go-localereader v0.0.1/go.mod h1:8fBrzywKY7BI3czFoHkuzRoWE9C+EiG4R1k4Cjx5p88=
32
+ github.com/mattn/go-runewidth v0.0.23 h1:7ykA0T0jkPpzSvMS5i9uoNn2Xy3R383f9HDx3RybWcw=
33
+ github.com/mattn/go-runewidth v0.0.23/go.mod h1:XBkDxAl56ILZc9knddidhrOlY5R/pDhgLpndooCuJAs=
34
+ github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI=
35
+ github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo=
36
+ github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA=
37
+ github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
38
+ github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
39
+ github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
40
+ github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
41
+ github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
42
+ github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
43
+ github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
44
+ github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
45
+ github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
46
+ github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
47
+ github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
48
+ github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
49
+ github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
50
+ go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
51
+ golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
52
+ golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
53
+ golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
54
+ golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
55
+ golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
56
+ golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
57
+ golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
58
+ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
59
+ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
60
+ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
61
+ gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
package/index.js ADDED
File without changes
package/package.json ADDED
@@ -0,0 +1,26 @@
1
+ {
2
+ "name": "@jeancodogno/specforce-kit",
3
+ "version": "0.1.0",
4
+ "description": "SpecForce Kit CLI - Distributed via GoReleaser",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/jeancodogno/specforce-kit.git"
8
+ },
9
+ "bin": {
10
+ "specforce": "bin/specforce"
11
+ },
12
+ "scripts": {
13
+ "postinstall": "go-npm install",
14
+ "uninstall": "go-npm uninstall"
15
+ },
16
+ "dependencies": {
17
+ "go-npm": "^0.1.1"
18
+ },
19
+ "goBinary": {
20
+ "name": "specforce",
21
+ "path": "./bin",
22
+ "url": "https://github.com/jeancodogno/specforce-kit/releases/download/v{{version}}/specforce-kit_{{platform}}_{{arch}}.{{extension}}"
23
+ },
24
+ "author": "Jean Codogno <jeancarlo.eng.comp@gmail.com>",
25
+ "license": "MIT"
26
+ }
@@ -0,0 +1,23 @@
1
+ package main
2
+
3
+ import (
4
+ "context"
5
+ "fmt"
6
+ "os"
7
+ "os/signal"
8
+ "syscall"
9
+
10
+ "github.com/jeancodogno/specforce-kit/src/internal/cli/cobra"
11
+ )
12
+
13
+ var version = "0.1.0"
14
+
15
+ func main() {
16
+ ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
17
+ defer stop()
18
+
19
+ if err := cobra.Execute(ctx, version); err != nil {
20
+ fmt.Fprintf(os.Stderr, "Error: %v\n", err)
21
+ os.Exit(1)
22
+ }
23
+ }
@@ -0,0 +1,7 @@
1
+ package main
2
+
3
+ import "testing"
4
+
5
+ func TestMain(t *testing.T) {
6
+ // Dummy test to avoid 'no such tool covdata' error in Go 1.25+
7
+ }
@@ -0,0 +1,70 @@
1
+ description: "Technical structure, system boundaries, layers, dependency direction, and persistence topology."
2
+ instruction: |
3
+ Generate the Architecture document strictly using the provided template. You are filling in a blueprint for a Spec-Driven Development (SDD) framework. Do not output any placeholder text; replace all sections with concrete project decisions.
4
+
5
+ Adhere to the following rules for each section:
6
+
7
+ 1. Stack & Tooling Baseline:
8
+ - Define the exact Backend language/framework (e.g., PHP/Symfony) and minimum version.
9
+ - Define the Frontend framework (e.g., Vue 3) and minimum version.
10
+ - Define the State Management strategy.
11
+ - Define the Data storage (primary DB, caching).
12
+ - Define the Tooling/Infra (e.g., Docker, Makefiles).
13
+
14
+ 2. API & Communication Paradigm:
15
+ - Specify the Client-to-Server protocol (e.g., RESTful JSON APIs).
16
+ - Specify the Internal-Services communication method.
17
+
18
+ 3. High-Level Architecture (Mermaid):
19
+ - Generate a `graph TB` Mermaid diagram.
20
+ - It MUST represent the macro-flow between the User, Frontend App, API Gateway, Domain/Application Layer, Database, and External Services.
21
+ - Group containerized environments if applicable.
22
+
23
+ 4. Architectural Principles:
24
+ - List 3-5 core principles. Ensure rules like "Domain logic MUST remain framework-agnostic" and explicit boundary definitions are included.
25
+
26
+ 5. Repository Topology:
27
+ - State explicitly if it is a `monorepo` or `single-repo`.
28
+ - Provide a clear technical rationale for this choice.
29
+
30
+ 6. Directory Structure:
31
+ - Provide a canonical directory tree using a text block (e.g., `repo/apps/`, `repo/packages/`, `repo/.specforce/`).
32
+
33
+ 7. Directory & Naming Standards:
34
+ - Define paths for feature specs (`.specforce/specs/{slug}/`) and docs (`.specforce/docs/`).
35
+ - Define source layout naming conventions (e.g., PascalCase for Domain, kebab-case for UI components).
36
+
37
+ 8. Observability Baseline:
38
+ - Define the requirements for structured logs, correlation ID propagation, and error traceability to Spec IDs.
39
+
40
+ CRITICAL: The final output must be pure Markdown, ready to be saved as `architecture.md`.
41
+ template: |
42
+ # Architecture
43
+
44
+ ## Stack & Tooling Baseline
45
+ - **Backend:**
46
+ - **Frontend:**
47
+ - **State Management:**
48
+ - **Data:**
49
+ - **Tooling/Infra:**
50
+
51
+ ## API & Communication Paradigm
52
+ - **Client-to-Server:**
53
+ - **Internal-Services:**
54
+
55
+ ## High-Level Architecture (Mermaid)
56
+ ```mermaid```
57
+
58
+ ## Architectural Principles
59
+
60
+ ## Repository Topology
61
+ - **Topology:** - **Rationale:**
62
+
63
+ ## Directory Structure
64
+
65
+ ## Directory & Naming Standards
66
+ - **Feature specs:** `.specforce/specs/{slug}/`
67
+ - **Constitution docs:** `.specforce/docs/`
68
+ - **Source layout:**
69
+
70
+ ## Observability Baseline
@@ -0,0 +1,52 @@
1
+ description: "Coding standards, testing strategy, verification rigor, rollout safety, and AI constraints."
2
+ instruction: |
3
+ Generate the Engineering document strictly using the provided template. You are filling in a blueprint for a Spec-Driven Development (SDD) framework. Do not output any placeholder text; replace all sections with concrete, rigid project decisions.
4
+
5
+ Adhere to the following rules for each section:
6
+
7
+ 1. Coding Standards:
8
+ - Define the exact linting tools and style guides for Backend (e.g., PHPStan Level 8, PSR-12) and Frontend (e.g., ESLint, Prettier).
9
+ - State strict typing rules (e.g., "All PHP methods MUST have return types").
10
+ - Establish limits on complexity (e.g., max function length, max nesting).
11
+
12
+ 2. Testing Strategy:
13
+ - Define the required testing frameworks (e.g., Pest for PHP, Vitest for Vue).
14
+ - Define the minimum code coverage percentage gate (e.g., 80%).
15
+ - State the requirement for regressions (e.g., "A failing test MUST be written before fixing a bug").
16
+
17
+ 3. Delivery & Definition of Done (DoD):
18
+ - Specify the commit message format (e.g., Conventional Commits).
19
+ - Define the mandatory checks for a PR/Feature to be considered "Done" (e.g., passing CI, observability implemented, Spec updated).
20
+
21
+ 4. AI Coding Constraints (CRITICAL FOR SDD):
22
+ - Establish rules for autonomous code generation.
23
+ - Mandate that the AI MUST NOT remove existing human-written comments unless they are obsolete.
24
+ - Require the AI to document complex regex or algorithmic choices.
25
+
26
+ CRITICAL: The final output must be pure Markdown, ready to be saved as `engineering.md`.
27
+ template: |
28
+ # Engineering
29
+
30
+ ## Coding Standards
31
+ - **Backend Style & Linters:**
32
+ - **Frontend Style & Linters:**
33
+ - **Typing Strictness:**
34
+ - **Complexity Limits:**
35
+
36
+ ## Testing Strategy
37
+ - **Frameworks:**
38
+ - **Coverage Gate:**
39
+ - **Unit Testing Rules:** Critical paths MUST have automated tests.
40
+ - **Regression Rules:** New behavior MUST include at least one verification test. Regressions MUST be captured with reproducible test cases.
41
+
42
+ ## Delivery Standards & DoD
43
+ - **Commit Standard:**
44
+ - **Definition of Done (DoD):**
45
+ - [ ] Code passes all linters and static analysis.
46
+ - [ ] Tests are written and passing.
47
+ - [ ] Observability/Logs are implemented for new features.
48
+
49
+ ## AI Coding Constraints
50
+ - The AI MUST NOT remove existing comments unless explicitly replacing them with better documentation.
51
+ - All newly generated public methods/functions MUST include docblocks or strict type hinting.
52
+ - [Add any other AI-specific safety rules]
@@ -0,0 +1,41 @@
1
+ description: "Project lifecycle rules, amendment policies, ownership, review processes, and AI boundaries."
2
+ instruction: |
3
+ Generate the Governance document strictly using the provided template. You are filling in a blueprint for a Spec-Driven Development (SDD) framework. Do not output any placeholder text; replace all blank sections with concrete project decisions.
4
+
5
+ Adhere to the following rules for each section:
6
+
7
+ 1. Versioning & Amendment:
8
+ - Keep the provided SemVer and Amendment process exactly as defined in the template. They are the core rules of the framework.
9
+
10
+ 2. Ownership & Review:
11
+ - Define the explicitly responsible Owner/Role for the constitution (e.g., "Lead Architect", "Core Engineering Team").
12
+ - Define the Review Cadence for the constitution (e.g., "Quarterly", "After every Major release").
13
+
14
+ 3. Agentic Authority & Boundaries (CRITICAL):
15
+ - Explicitly define what autonomous AI agents CAN do (e.g., "AI agents MAY draft new Specs and propose Memorial updates").
16
+ - Explicitly define what AI agents CANNOT do without human approval (e.g., "AI agents MUST NOT modify ANY constitution file in .specforce/docs/ without explicit human approval and a version bump").
17
+ - Establish the protocol for when the AI detects a conflict between a prompt and the Constitution (e.g., "The AI MUST refuse the prompt and cite the violated Principle/Rule").
18
+
19
+ CRITICAL: The final output must be pure Markdown, ready to be saved as `governance.md`.
20
+ template: |
21
+ # Governance
22
+
23
+ ## Versioning Policy (SemVer)
24
+ - **MAJOR:** Breaking constitutional or architectural process change. Requires team consensus.
25
+ - **MINOR:** New principle or standard added without breaking prior commitments.
26
+ - **PATCH:** Clarifications, typo fixes, wording, and non-functional adjustments.
27
+
28
+ ## Amendment Process
29
+ 1. Propose the change with a clear rationale and impact analysis.
30
+ 2. Classify the SemVer impact (Major/Minor/Patch).
31
+ 3. Update all affected docs in `.specforce/docs/`.
32
+ 4. Record the version bump and the amendment date in the document's header.
33
+
34
+ ## Ownership & Review
35
+ - **Owner:**
36
+ - **Review Cadence:**
37
+
38
+ ## Agentic Authority & Boundaries
39
+ - **Permitted AI Autonomous Actions:**
40
+ - **Prohibited AI Actions (Requires Human Approval):**
41
+ - **Conflict Resolution Protocol:**
@@ -0,0 +1,55 @@
1
+ description: "Cross-session memory, durable lessons learned, and critical project reminders."
2
+ instruction: |
3
+ Generate the Memorial document strictly using the provided template. You are filling in a blueprint for a Spec-Driven Development (SDD) framework.
4
+
5
+ Adhere to the following rules for bootstrapping this file:
6
+
7
+ 1. DO NOT invent or hallucinate past actions, lessons, or pending decisions. This is the initialization phase. Leave the structural placeholders empty but ready for use.
8
+ 2. The section "> FOR AI AGENTS" is the most critical part of this file. It MUST be copied verbatim into the final `memorial.md` document. This block serves as the runtime prompt for all future agents interacting with the repository.
9
+ 3. Keep the exact Markdown formatting for the data blocks (Critical Now, Last Actions, etc.) so future agents have a strict schema to follow when appending data.
10
+
11
+ CRITICAL: The final output must be pure Markdown, ready to be saved as `memorial.md`.
12
+ template: |
13
+ # Memorial (Active Memory)
14
+
15
+ > **FOR AI AGENTS: RULES OF ENGAGEMENT**
16
+ > This is your cross-session memory file. You MUST obey these rules:
17
+ > 1. **READ THIS FIRST** before starting any task, debugging, or writing code in this repository.
18
+ > 2. **TRIAGE:** Read `Critical Now` first, then `Last Actions`. Only read lessons if they match your current scope.
19
+ > 3. **STRICT LIMITS (DO NOT BLOAT):** > - Max 3 `Critical Now` bullets.
20
+ > - Max 5 `Last Actions` entries.
21
+ > - Max 7 `Active Lessons`.
22
+ > - Max 5 `Pending Decisions`.
23
+ > 4. **GARBAGE COLLECTION:** If a list is full, you MUST delete the oldest/least relevant item before adding a new one.
24
+ > 5. **DISTILLATION:** If a lesson or decision becomes a permanent rule, you MUST move it to the official Constitution files (`engineering.md`, `architecture.md`, etc.) and completely delete it from here.
25
+
26
+ ---
27
+
28
+ ## Critical Now
29
+ - [YYYY-MM-DD] [Scope] [System initialized. Awaiting first actions.]
30
+
31
+ ## Last Actions
32
+ - **Date:**
33
+ - **Scope:**
34
+ - **Completed:**
35
+ - **Next:**
36
+ - **Relevant Files:**
37
+
38
+ ## Active Lessons & Anti-Patterns
39
+ - **First Seen:**
40
+ - **Last Seen:**
41
+ - **Scope:**
42
+ - **Symptom:**
43
+ - **Avoid:**
44
+ - **Do Instead:**
45
+ - **Recurrence Count:**
46
+ - **Status:**
47
+ - **Distill To:**
48
+
49
+ ## Pending Decisions (Need Distillation)
50
+ - **Date:**
51
+ - **Scope:**
52
+ - **Decision:**
53
+ - **Why:**
54
+ - **Validate By:**
55
+ - **Distill To:**
@@ -0,0 +1,54 @@
1
+ description: "Core values, philosophy, and non-negotiable cultural or technical axioms."
2
+ instruction: |
3
+ Generate the Principles document strictly using the provided template. You are filling in a blueprint for a Spec-Driven Development (SDD) framework. Do not output any placeholder text; replace all sections with concrete project decisions.
4
+
5
+ Adhere to the following rules for each section:
6
+
7
+ 1. Mission:
8
+ - Define a clear, single-paragraph statement of the core problem being solved and the primary value proposition.
9
+
10
+ 2. User Personas:
11
+ - Define the primary users of the system.
12
+ - For each persona, explicitly state their Role, Primary Goal, and Key Pain Point.
13
+ - Note: These personas MUST dictate authorization and UX design rules in future specs.
14
+
15
+ 3. Golden Rules (The Tie-Breakers):
16
+ - List 3 to 5 non-negotiable axioms (e.g., "Data privacy is prioritized over feature speed," or "The UI must remain fully functional without JavaScript").
17
+ - Instruct the AI that these rules are absolute tie-breakers for any architectural or design disputes.
18
+
19
+ 4. Product Boundaries:
20
+ - In Scope: List 3-4 core capabilities the product MUST have.
21
+ - Out of Scope (Anti-Goals): List explicitly what the product MUST NOT do to prevent AI hallucination and feature creep.
22
+
23
+ CRITICAL AI DIRECTIVE: The LLM MUST use this document as the ultimate source of truth. If a user prompt or a draft Spec contradicts the Golden Rules or Out of Scope boundaries, the AI MUST refuse the change and cite this document.
24
+
25
+ CRITICAL: The final output must be pure Markdown, ready to be saved as `principles.md`.
26
+ template: |
27
+ # Principles
28
+
29
+ ## Mission
30
+
31
+ ## User Personas
32
+ - **Persona 1:**
33
+ - **Role:**
34
+ - **Goal:**
35
+ - **Pain Point:**
36
+ - **Persona 2:**
37
+ - **Role:**
38
+ - **Goal:**
39
+ - **Pain Point:**
40
+
41
+ ## Golden Rules
42
+ 1. **Rule 1:**
43
+ 2. **Rule 2:**
44
+ 3. **Rule 3:**
45
+
46
+ ## Product Boundaries
47
+
48
+ ### In Scope
49
+ -
50
+ -
51
+
52
+ ### Out of Scope (Anti-Goals)
53
+ -
54
+ -
@@ -0,0 +1,47 @@
1
+ description: "Authentication, authorization, roles, permissions, privacy, and data protection rules."
2
+ instruction: |
3
+ Generate the Security document strictly using the provided template. You are filling in a blueprint for a Spec-Driven Development (SDD) framework. Do not output any placeholder text; replace all sections with concrete project decisions.
4
+
5
+ Adhere to the following rules for each section:
6
+
7
+ 1. Identity & Access Control:
8
+ - Define the exact Authentication strategy (e.g., JWT with RS256, Session cookies, OAuth2).
9
+ - Define the token/session lifecycle (e.g., Access tokens expire in 15m, Refresh in 7d).
10
+ - Specify the Authorization model (e.g., RBAC, ABAC) and the strict rule for tenant isolation to prevent IDOR (Insecure Direct Object Reference).
11
+
12
+ 2. Data Protection & Cryptography:
13
+ - Specify encryption standards for Data at Rest (e.g., AES-256) and Data in Transit (e.g., TLS 1.3).
14
+ - Explicitly define how application secrets MUST be managed (e.g., strictly via environment variables or a Secret Manager).
15
+
16
+ 3. Auditing & Logging:
17
+ - List the specific events that MUST trigger a security audit log (e.g., authentication failures, permission modifications, data exports).
18
+ - Define the masking policy to ensure PII (Personally Identifiable Information) or passwords never leak into logs.
19
+
20
+ 4. AI Security Constraints (CRITICAL FOR SDD):
21
+ - Mandate that the AI MUST NEVER hardcode passwords, API keys, or dummy tokens in any generated file.
22
+ - Mandate that the AI MUST ALWAYS use parameterized queries or the official project ORM to prevent SQL Injection. No raw string concatenation for SQL is allowed.
23
+ - Mandate that all inputs MUST be validated at the boundary and all outputs encoded to prevent XSS.
24
+
25
+ CRITICAL: The final output must be pure Markdown, ready to be saved as `security.md`.
26
+ template: |
27
+ # Security Posture
28
+
29
+ ## Identity & Access Control
30
+ - **Authentication Strategy:**
31
+ - **Token/Session Lifecycle:**
32
+ - **Authorization Model:**
33
+ - **Tenant Isolation (IDOR Prevention):**
34
+
35
+ ## Data Protection & Cryptography
36
+ - **Data in Transit:**
37
+ - **Data at Rest:**
38
+ - **Secret Management:**
39
+
40
+ ## Auditing & Logging
41
+ - **Auditable Events:**
42
+ - **Log Sanitization & PII:**
43
+
44
+ ## AI Security Constraints
45
+ - The AI MUST NEVER hardcode passwords, tokens, or API keys in the source code. All secrets MUST be mocked via environment variables.
46
+ - The AI MUST ALWAYS use parameterized queries or the framework's native ORM/QueryBuilder. Raw SQL string concatenation is strictly forbidden.
47
+ - The AI MUST strictly validate all API and Controller inputs using the framework's validator before any domain logic execution.