@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,334 @@
1
+ package agent
2
+
3
+ import (
4
+ "context"
5
+ "fmt"
6
+ "io/fs"
7
+ "os"
8
+ "path/filepath"
9
+ "strings"
10
+
11
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
12
+ "github.com/jeancodogno/specforce-kit/src/internal/installer"
13
+ "gopkg.in/yaml.v3"
14
+ )
15
+
16
+ // globalEnabledAgents defines which agents are allowed to write artifacts to global system paths.
17
+ var globalEnabledAgents = []string{"codex"}
18
+
19
+ // Transformer defines how to transform a blueprint into a target format.
20
+ type Transformer func(bp *core.Blueprint, mapping core.MappingConfig) string
21
+
22
+ var transformers = map[string]Transformer{
23
+ ".toml": func(bp *core.Blueprint, mapping core.MappingConfig) string {
24
+ desc := bp.Metadata.Description
25
+ if desc == "" {
26
+ desc = mapping.Name
27
+ }
28
+ // Gemini TOML format: REQ-2 AC-5
29
+ return fmt.Sprintf("description = %q\nprompt = \"\"\"\n%s\n\"\"\"\n", desc, bp.Content)
30
+ },
31
+ }
32
+
33
+ // LoadKitConfig parses the kit.yaml configuration file. It prefers embedded defaults from kitFS
34
+ // and applies optional overrides from the project root if kit.yaml exists there.
35
+ func LoadKitConfig(kitFS fs.FS, root string) (*core.KitConfig, error) {
36
+ // 1. Load from kitFS (embedded defaults)
37
+ data, err := fs.ReadFile(kitFS, "kit.yaml")
38
+ if err != nil {
39
+ return nil, fmt.Errorf("failed to read embedded kit.yaml: %w", err)
40
+ }
41
+
42
+ var config core.KitConfig
43
+ if err := yaml.Unmarshal(data, &config); err != nil {
44
+ return nil, fmt.Errorf("failed to parse embedded kit.yaml: %w", err)
45
+ }
46
+
47
+ // 2. Load from root/kit.yaml (user overrides) - OPTIONAL
48
+ overridePath, err := core.SecurePath(root, "kit.yaml")
49
+ if err == nil {
50
+ // #nosec G304 - Path is secured by SecurePath
51
+ overrideData, err := os.ReadFile(overridePath)
52
+ if err == nil {
53
+ var override core.KitConfig
54
+ if err := yaml.Unmarshal(overrideData, &override); err == nil {
55
+ // Basic merge logic: replace tools defined in override
56
+ if override.Tools != nil {
57
+ if config.Tools == nil {
58
+ config.Tools = make(map[string]core.ToolRoute)
59
+ }
60
+ for id, route := range override.Tools {
61
+ config.Tools[id] = route
62
+ }
63
+ }
64
+ }
65
+ }
66
+ }
67
+
68
+ return &config, nil
69
+ }
70
+
71
+ // AdaptArtifacts reads blueprints from the given kitFS and adapts them for the specified agent.
72
+ func AdaptArtifacts(ctx context.Context, root string, kitFS fs.FS, agent string, ui core.UI, opts installer.Options) error {
73
+ if ui != nil {
74
+ ui.SubTask(fmt.Sprintf("Adapting artifacts for %s...", agent))
75
+ }
76
+
77
+ kitConfig, err := LoadKitConfig(kitFS, root)
78
+ if err != nil {
79
+ return err
80
+ }
81
+
82
+ return fs.WalkDir(kitFS, ".", func(path string, d fs.DirEntry, err error) error {
83
+ if err != nil {
84
+ return err
85
+ }
86
+
87
+ if err := ctx.Err(); err != nil {
88
+ return err
89
+ }
90
+
91
+ if d.IsDir() {
92
+ return nil
93
+ }
94
+
95
+ // Only parse blueprints (YAML files with structured metadata and content)
96
+ matched, _ := filepath.Match("*.yaml", d.Name())
97
+ if !matched || d.Name() == "mapping.yaml" || d.Name() == "manifest.yaml" {
98
+ return nil
99
+ }
100
+
101
+ return processBlueprint(ctx, root, kitFS, kitConfig, path, agent, opts)
102
+ })
103
+ }
104
+
105
+ func processBlueprint(ctx context.Context, root string, kitFS fs.FS, kitConfig *core.KitConfig, path string, agent string, opts installer.Options) error {
106
+ data, err := fs.ReadFile(kitFS, path)
107
+ if err != nil {
108
+ return fmt.Errorf("failed to read blueprint %s: %w", path, err)
109
+ }
110
+
111
+ bp, err := core.ParseBlueprint(path, data)
112
+ if err != nil {
113
+ return fmt.Errorf("failed to parse blueprint %s: %w", path, err)
114
+ }
115
+
116
+ mapping, err := resolveMapping(kitConfig, path, bp, agent)
117
+ if err != nil {
118
+ return err
119
+ }
120
+ if mapping == nil {
121
+ return nil
122
+ }
123
+
124
+ // REQ-2: Check if this artifact should be installed based on the target path
125
+ if !installer.ShouldInstall(mapping.Path, opts) {
126
+ return nil
127
+ }
128
+
129
+ var targetDir, targetFile string
130
+ if isGlobalEnabled(agent) {
131
+ targetDir = mapping.Path
132
+ if !filepath.IsAbs(targetDir) {
133
+ targetDir = filepath.Join(root, targetDir)
134
+ }
135
+ targetFile = filepath.Join(targetDir, mapping.Name+mapping.Ext)
136
+ } else {
137
+ var err error
138
+ targetDir, err = core.SecurePath(root, mapping.Path)
139
+ if err != nil {
140
+ return fmt.Errorf("security: %w", err)
141
+ }
142
+ targetFile, err = core.SecurePath(root, filepath.Join(mapping.Path, mapping.Name+mapping.Ext))
143
+ if err != nil {
144
+ return fmt.Errorf("security: %w", err)
145
+ }
146
+ }
147
+
148
+ if err := os.MkdirAll(targetDir, 0750); err != nil {
149
+ return fmt.Errorf("failed to create target directory %s: %w", targetDir, err)
150
+ }
151
+
152
+ category := strings.Split(filepath.ToSlash(path), "/")[0]
153
+ content := applyTransformation(bp, *mapping, path, category)
154
+
155
+ // #nosec G306 - Path is secured by SecurePath
156
+ if err := os.WriteFile(targetFile, []byte(content), 0600); err != nil {
157
+ return fmt.Errorf("failed to write adapted artifact %s: %w", targetFile, err)
158
+ }
159
+
160
+ return nil
161
+ }
162
+
163
+ func resolveMapping(kitConfig *core.KitConfig, path string, bp *core.Blueprint, agent string) (*core.MappingConfig, error) {
164
+ parts := strings.Split(filepath.ToSlash(path), "/")
165
+ if len(parts) == 0 {
166
+ return nil, nil
167
+ }
168
+
169
+ category := parts[0]
170
+ slug := strings.TrimSuffix(filepath.Base(path), filepath.Ext(path))
171
+
172
+ toolRoute, ok := kitConfig.Tools[agent]
173
+ if !ok {
174
+ return nil, core.ErrToolMappingNotFound
175
+ }
176
+
177
+ mapping, hasMapping := toolRoute.Mappings[category]
178
+
179
+ if !hasMapping {
180
+ if bp.Metadata.Mapping == nil {
181
+ return nil, nil
182
+ }
183
+ override, ok := bp.Metadata.Mapping[agent]
184
+ if !ok {
185
+ return nil, nil
186
+ }
187
+ mapping = override
188
+ } else {
189
+ applyBlueprintOverrides(&mapping, bp, agent)
190
+ }
191
+
192
+ initialPath := mapping.Path
193
+ applyWildcards(&mapping, slug, parts, initialPath)
194
+
195
+ // Default naming logic: If mapping.Name is missing, resolve it based on source filename
196
+ if mapping.Name == "" {
197
+ mapping.Name = slug
198
+ }
199
+
200
+ // Resolve final target path
201
+ rawTarget := mapping.Target
202
+ if rawTarget == "" {
203
+ rawTarget = toolRoute.Target
204
+ }
205
+
206
+ target := core.ExpandPath(rawTarget)
207
+ if strings.HasPrefix(target, "~") {
208
+ return nil, fmt.Errorf("failed to resolve home directory for path: %s", target)
209
+ }
210
+
211
+ // Use filepath.Join to combine target and the mapping's internal path
212
+ mapping.Path = filepath.Clean(filepath.Join(target, mapping.Path))
213
+
214
+ return &mapping, nil
215
+ }
216
+
217
+ func isGlobalEnabled(agent string) bool {
218
+ for _, a := range globalEnabledAgents {
219
+ if a == agent {
220
+ return true
221
+ }
222
+ }
223
+ return false
224
+ }
225
+
226
+ func applyBlueprintOverrides(mapping *core.MappingConfig, bp *core.Blueprint, agent string) {
227
+ if bp.Metadata.Mapping != nil {
228
+ if override, ok := bp.Metadata.Mapping[agent]; ok {
229
+ if override.Path != "" {
230
+ mapping.Path = override.Path
231
+ }
232
+ if override.Name != "" {
233
+ mapping.Name = override.Name
234
+ }
235
+ if override.Ext != "" {
236
+ mapping.Ext = override.Ext
237
+ }
238
+ }
239
+ }
240
+ }
241
+
242
+ func applyWildcards(mapping *core.MappingConfig, slug string, parts []string, initialPath string) {
243
+ hasWildcardInPath := strings.Contains(mapping.Path, "*")
244
+ hasWildcardInName := strings.Contains(mapping.Name, "*")
245
+ mapping.Path = strings.ReplaceAll(mapping.Path, "*", slug)
246
+ mapping.Name = strings.ReplaceAll(mapping.Name, "*", slug)
247
+
248
+ if !hasWildcardInPath && !hasWildcardInName && len(parts) > 2 {
249
+ subDir := filepath.Join(parts[1 : len(parts)-1]...)
250
+ mapping.Path = filepath.Join(mapping.Path, subDir)
251
+ }
252
+
253
+ // If name has wildcard but path is fixed, we might want flat export.
254
+ // This specifically handles the Antigravity/Codex case where Path was intended to be "."
255
+ // but it was actually initialized with some value from the mapping.
256
+ if hasWildcardInName && !hasWildcardInPath && initialPath == "." {
257
+ mapping.Path = "."
258
+ }
259
+ }
260
+
261
+ func applyTransformation(bp *core.Blueprint, mapping core.MappingConfig, sourcePath string, category string) string {
262
+ if transformer, ok := transformers[mapping.Ext]; ok {
263
+ return transformer(bp, mapping)
264
+ }
265
+
266
+ // REQ-2: Standardized YAML Frontmatter Headers for Markdown
267
+ if mapping.Ext == ".md" {
268
+ return injectYAMLHeader(bp, mapping, sourcePath, category)
269
+ }
270
+
271
+ return bp.Content
272
+ }
273
+
274
+ func injectYAMLHeader(bp *core.Blueprint, mapping core.MappingConfig, sourcePath string, category string) string {
275
+ var header strings.Builder
276
+ header.WriteString("---\n")
277
+
278
+ // Resolve the display name: prefer metadata name, fallback to mapping name
279
+ displayName := bp.Metadata.Name
280
+ if displayName == "" {
281
+ displayName = mapping.Name
282
+ }
283
+
284
+ // REQ-2 AC-1: Agent header
285
+ if category == "agents" {
286
+ fmt.Fprintf(&header, "name: %s\n", displayName)
287
+ fmt.Fprintf(&header, "description: %s\n", bp.Metadata.Description)
288
+ }
289
+
290
+ // REQ-2 AC-2 & AC-3: Skill header (only for primary SKILL.md)
291
+ if category == "skills" {
292
+ if mapping.Name == "SKILL" {
293
+ fmt.Fprintf(&header, "name: %s\n", displayName)
294
+ fmt.Fprintf(&header, "description: %s\n", bp.Metadata.Description)
295
+ if bp.Metadata.Version != "" {
296
+ fmt.Fprintf(&header, "version: %s\n", bp.Metadata.Version)
297
+ }
298
+ if bp.Metadata.Priority != "" {
299
+ fmt.Fprintf(&header, "priority: %s\n", bp.Metadata.Priority)
300
+ }
301
+ } else {
302
+ // Skills secondary files don't get headers
303
+ return bp.Content
304
+ }
305
+ }
306
+
307
+ // REQ-2 AC-4: Command header
308
+ if category == "commands" {
309
+ fmt.Fprintf(&header, "name: %s\n", displayName)
310
+ fmt.Fprintf(&header, "description: %s\n", bp.Metadata.Description)
311
+ }
312
+
313
+ // If no header fields were added (unknown type), just return content
314
+ if header.Len() == 4 { // Only "---\n"
315
+ return bp.Content
316
+ }
317
+
318
+ header.WriteString("---\n\n")
319
+ header.WriteString(bp.Content)
320
+ return header.String()
321
+ }
322
+
323
+ // ResolveTemplatePath returns the path to a template, preferring the project-level
324
+ func ResolveTemplatePath(root, templateName string) string {
325
+ projectPath, err := core.SecurePath(root, filepath.Join(".specforce/templates", templateName))
326
+ if err != nil {
327
+ return ""
328
+ }
329
+ if _, err := os.Stat(projectPath); err == nil {
330
+ return projectPath
331
+ }
332
+
333
+ return projectPath
334
+ }