@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,129 @@
1
+ # UI/UX
2
+
3
+ ## 1. Visual Theme & Atmosphere
4
+ - **Framework/Base:** Bubbletea (TUI) with Lipgloss for styling.
5
+ - **Theme:** Ghost in the Machine.
6
+ - **Atmosphere:** Surgical, alien, and extremely clean. Conveys the idea of an autonomous agent working flawlessly.
7
+ - **Density Posture:** Compact (Optimized for standard terminal dimensions).
8
+ - **Design Philosophy:** Optimizes for readability and fast keyboard navigation; avoids unnecessary visual clutter.
9
+ - **Signature Moves:** Consistent "Branding" boxes, ASCII art logos (Braille-based), and color-coded status indicators. Minimalist separators instead of thick borders.
10
+
11
+ ## 2. Color Palette & Roles
12
+ ### Brand & Accent
13
+ - **Primary Brand:** `#00FA9A` (Mint Green) | Primary borders, brand name, and major headings.
14
+ - **Secondary Brand:** `#00FFFF` (Cyan) | Subheadings and active selection highlights.
15
+ - **Accent:** `#E0FFFF` (Silver/Ice) | Muted subtitles and special focus elements.
16
+
17
+ ### Text & Feedback
18
+ - **Primary Text:** `#FFFFFF` | Standard body text and labels.
19
+ - **Secondary Text / Metadata:** `#808080` | Muted information, metadata, captions, and pending items.
20
+ - **Error:** `#FF5F5F` | Critical failures, validation errors, and destructive actions.
21
+ - **Success / Done:** `#5FFF87` | Successful operations and completed items (`◉`).
22
+ - **Warning / In-Progress:** `#FFFFAF` | Non-critical alerts and active/working items (`◉`).
23
+ - **Info:** `#87AFFF` | Informational messages and help context.
24
+
25
+ ### Iconography & Status States
26
+ - **Done:** `◉` (Filled Circle) in **Success Green** (`#5FFF87`).
27
+ - **In-Progress:** `◉` (Filled Circle) in **Warning/Orange** (`#FFFFAF`).
28
+ - **Pending / Inactive:** `○` (Empty Circle) in **Secondary Gray** (`#808080`).
29
+ - **Description / Context:** `↳` (Right Arrow) in **Secondary Gray** (`#808080`) for indented details.
30
+
31
+ ### Surface & Border
32
+ - **Canvas:** `#000000` | Terminal background.
33
+ - **Surface:** `#121212` | Highlighted block backgrounds.
34
+ - **Muted Surface:** `#080808` | Secondary block backgrounds.
35
+ - **Border:** `#444444` | Standard UI borders, preferring thin or dashed lines.
36
+
37
+ ## 3. Typography Rules
38
+ ### Font Family
39
+ - **Primary:** Monospace (System Default).
40
+ - **Secondary:** N/A.
41
+ - **Usage Logic:** Hierarchy is strictly created via color, weight (bold), and whitespace.
42
+
43
+ ### Hierarchy
44
+ | Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
45
+ |---|---|---|---|---|---|---|
46
+ | Display | Monospace | N/A | Bold | N/A | N/A | Brand/Logo |
47
+ | Heading | Monospace | N/A | Bold | N/A | N/A | Primary sections |
48
+ | Subheading | Monospace | N/A | Normal | N/A | N/A | Secondary sections |
49
+ | Body | Monospace | N/A | Normal | N/A | N/A | Content text |
50
+ | UI Label | Monospace | N/A | Bold | N/A | N/A | Input labels |
51
+ | Caption | Monospace | N/A | Normal | N/A | N/A | Muted metadata |
52
+
53
+ ### Content Voice
54
+ - **Headlines:** Direct and imperative.
55
+ - **Buttons & Actions:** Clear and concise (e.g., [ Confirm ], [ Cancel ]).
56
+ - **Form Guidance:** Helpful and instructional.
57
+
58
+ ## 4. Component Stylings
59
+ ### Buttons
60
+ - **Primary:** High-contrast text or inverted colors (e.g., `[ Confirm ]`).
61
+ - **Secondary:** Standard text within brackets (e.g., `[ Back ]`).
62
+ - **Destructive:** Red text or background.
63
+
64
+ ### Cards & Panels
65
+ - **Container Style:** Lipgloss `Normal` or custom clean separators (e.g., `-` and `|` with `+` corners). Avoid `Thick` borders.
66
+ - **State Behavior:** Borders change color based on focus or status (e.g., Mint Green for active).
67
+
68
+ ### Inputs & Forms
69
+ - **Input Baseline:** Clear prefix (e.g., `> ` or `? `).
70
+ - **Focus Style:** Cursor highlight or colored prefix.
71
+ - **Error Style:** Red text below the input.
72
+
73
+ ### Navigation
74
+ - **Primary Navigation:** List-based selection with cursor indicator.
75
+ - **Active State:** Cyan or Mint Green highlight.
76
+ - **Secondary Navigation:** Footer shortcuts (e.g., `esc: back • q: quit`).
77
+
78
+ ## 5. Layout Principles
79
+ - **Spacing Scale:** 1-character/line baseline grid.
80
+ - **Grid Logic:** Strictly vertical stacking with 1-line internal padding.
81
+ - **Whitespace Philosophy:** Use empty lines to separate logical contexts.
82
+ - **Page Structure Bias:** Centered or Left-aligned with a fixed width for core content.
83
+ - **Navigation Distribution:** Persistent footer for global actions.
84
+
85
+ ## 6. Depth & Elevation
86
+ | Level | Treatment | Use |
87
+ |---|---|---|
88
+ | Flat | No border | Backgrounds, passive surfaces |
89
+ | Raised | Single border | Cards, status blocks |
90
+ | Interactive Hover | Highlighted text | Active menu items, buttons |
91
+ | Modal / Priority | Clean solid border | Dialogs, progress bars, blocking UI |
92
+
93
+ - **Shadow Philosophy:** N/A (TUI).
94
+ - **Surface Hierarchy:** Higher priority elements use brighter border colors.
95
+
96
+ ## 7. Do's and Don'ts
97
+ ### Do
98
+ - Use consistent ASCII art branding across all major views.
99
+ - Ensure all interactive elements provide visual feedback on focus.
100
+ - Adhere to the 80-character width standard for core content.
101
+
102
+ ### Don't
103
+ - Use blinking text or excessive flashing colors.
104
+ - Depend on mouse-only interactions.
105
+ - Overcrowd a single screen; use scrolling or multi-step wizards.
106
+
107
+ ## 8. Responsive Behavior
108
+ | Breakpoint | Width | Key Changes |
109
+ |---|---|---|
110
+ | Mobile | < 40 chars | Minimalist mode; single-column only. |
111
+ | Tablet | < 80 chars | Compact mode; standard layout. |
112
+ | Desktop | > 80 chars | Expanded mode; sidebars allowed. |
113
+ | Large Desktop | > 120 chars | Maximum readability; additional gutters. |
114
+
115
+ - **Touch Targets:** N/A (Keyboard-centric).
116
+ - **Collapsing Strategy:** Hide non-essential metadata on small terminals.
117
+ - **Responsive Priority:** Command inputs and core status are prioritized.
118
+
119
+ ## 9. Agent Prompt Guide
120
+ ### Quick Reference
121
+ - **Theme Summary:** Ghost in the Machine (TUI).
122
+ - **Primary Colors:** Mint Green (#00FA9A), Cyan (#00FFFF), and Silver/Ice (#E0FFFF).
123
+ - **Typography Summary:** Monospace only; hierarchy via weight/color.
124
+ - **Key Surface Rules:** Borders define depth; spacing defines context. Prefer thin/clean lines over thick borders.
125
+
126
+ ### Example Prompts
127
+ - "Build a TUI component using Lipgloss that represents a project status card with a thin Mint Green border and a green success label."
128
+ - "Build a Bubbletea form for gathering user input, ensuring the prompt prefix changes to red on validation failure."
129
+ - "When designing this TUI layout, ensure it remains readable on an 80x24 terminal by using vertical stacking and minimal padding."
File without changes
package/AGENTS.md ADDED
@@ -0,0 +1,36 @@
1
+ <!-- SPECFORCE_AGENTS_START -->
2
+ # AI Agent Collaboration Guide
3
+
4
+ This project uses **Specforce** for Spec-Driven Development (SDD). As an AI agent, you MUST adhere to the following rules:
5
+
6
+ ## 1. Spec-Driven Development (SDD) Protocol
7
+ - **Specs First:** Never write implementation code until a corresponding Specification (requirements.md, design.md, tasks.md) exists and is approved. You MUST consult spec artifacts using the Specforce CLI (e.g., specforce spec list, specforce spec status <slug> --json, and specforce spec artifact <name> --json) rather than reading the raw markdown files directly.
8
+ - **Atomic Tasks:** Follow the exact sequence of the tasks.md roadmap. Mark tasks as [DONE] or [FINISHED] sequentially.
9
+ - **Verification:** Execute the exact verification/TDD steps defined in the tasks.md file before marking a task as complete.
10
+
11
+ ## 2. Project Constitution
12
+ Before proposing architectural changes or adding new patterns, you MUST review the relevant Constitution documents located in .specforce/docs/:
13
+ - principles.md: Core values, philosophy, and cultural/technical axioms.
14
+ - architecture.md: System boundaries, dependency direction, and persistence topology.
15
+ - ui-ux.md: Visual direction, interaction patterns, and aesthetic DNA.
16
+ - security.md: AuthZ, roles, permissions, and data protection rules.
17
+ - engineering.md: Coding standards, testing strategy, and refactoring guidelines.
18
+ - governance.md: Project lifecycle rules, ownership, and AI boundaries.
19
+ - memorial.md: Durable lessons learned and cross-session memory.
20
+
21
+ ## 3. Custom Hooks Configuration
22
+ Specforce allows developers to gate state transitions (e.g., finishing a task) using custom hooks. You can configure these in the project root's config.yaml:
23
+
24
+ ```yaml
25
+ # config.yaml example
26
+ hooks:
27
+ on_task_finish:
28
+ command: "make lint && make test"
29
+ on_spec_finish:
30
+ command: "make build"
31
+ ```
32
+ If a hook fails, the state transition will be blocked.
33
+
34
+ *Note: The content above is managed by Specforce. Do not edit inside these markers.*
35
+ <!-- SPECFORCE_AGENTS_END -->
36
+
@@ -0,0 +1,81 @@
1
+ # Contributing to Specforce Kit
2
+
3
+ First off, thank you for considering contributing to Specforce Kit! It's people like you that make Specforce a great tool for the entire AI-Engineering community.
4
+
5
+ ## 🚀 Our Philosophy: Spec-First
6
+ We drink our own champagne. **All new features, bug fixes, or architectural changes in this repository MUST follow the Spec-Driven Development (SDD) lifecycle.**
7
+
8
+ 1. **Specification:** Every change starts with a Spec via your AI agent (`/spf:spec`).
9
+ 2. **Implementation:** Once approved, we implement using the Specforce roadmap (`/spf:implement`).
10
+ 3. **Verification & Archive:** Automated tests and manual TUI verification are mandatory before closing the loop (`/spf:archive`).
11
+
12
+ ---
13
+
14
+ ## 🐛 Reporting Issues
15
+
16
+ ### Bug Reports
17
+ - Use the GitHub Issue tracker.
18
+ - Describe the expected behavior vs. actual behavior.
19
+ - Provide a minimal reproduction script or steps.
20
+ - Include your OS and Specforce version (`specforce version`).
21
+
22
+ ### Feature Requests
23
+ - We love new ideas! Please open an issue to discuss the "Why" and "Value" before diving into technical details.
24
+
25
+ ---
26
+
27
+ ## 🛠 Pull Request Process
28
+
29
+ 1. **Fork and Branch:** Create a feature branch from `main`.
30
+ 2. **Create a Spec:** Use your preferred AI agent (Claude Code, Cursor, etc.) and run the `/spf:spec {description}` slash command to generate the `requirements.md`, `design.md`, and `tasks.md`.
31
+ 3. **Implement:** Use the `/spf:implement` command to let the agent execute the tasks.
32
+ 4. **Code Standards:**
33
+ - Language: Go 1.26+
34
+ - Formatting: `gofmt` is mandatory.
35
+ - Linting: Must pass `golangci-lint`.
36
+ - Standards: Adhere to our project Constitution.
37
+ 5. **Tests:** All new logic must have unit tests. Regression tests are required for bug fixes.
38
+ 6. **Archive & Commit:** Run `/spf:archive` to update the global Constitution. Use [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`).
39
+ 7. **Submit:** Open a PR against the `main` branch. Ensure the CI pipeline passes.
40
+
41
+ ---
42
+
43
+ ## 🤖 Kit Development (New Agent Support)
44
+
45
+ Specforce Kit is built to be model-agnostic. We welcome contributions that add support for new AI agents or improve existing ones.
46
+
47
+ ### What is a Kit?
48
+ A Kit is a set of instructions, rules, and tool mappings that allow an AI agent to interact with the Specforce framework. These are stored in hidden directories to ensure native discovery by the agents (e.g., `.claude/`, `.gemini/`, `.kilocode/`, etc.).
49
+
50
+ ### Creating a New Kit
51
+ 1. **Define the Instructions:** Create the necessary markdown files (e.g., `SKILL.md`, `commands.md`) that teach the agent how to call `specforce` CLI commands via the slash commands (`/spf:spec`, `/spf:implement`, etc.).
52
+ 2. **Ensure Context Segmentation:** Make sure the new agent integration respects our **Segmented Constitution** model, loading only the necessary architecture, UI/UX, or security rules when needed, rather than dumping everything into the context window.
53
+
54
+ ---
55
+
56
+ ## 🏗 Development Environment
57
+
58
+ ### Prerequisites
59
+ - Go 1.26+
60
+ - Make
61
+
62
+ ### Setup
63
+ ```bash
64
+ git clone https://github.com/jeancodogno/specforce-kit.git
65
+ cd specforce-kit
66
+ make build
67
+ make install
68
+ ```
69
+
70
+ ### Running Tests
71
+ ```bash
72
+ make test
73
+ ```
74
+
75
+ ---
76
+
77
+ ## 📜 Code of Conduct
78
+ By participating in this project, you agree to abide by our project's Code of Conduct and maintain a professional and respectful environment for all contributors.
79
+
80
+ ---
81
+ <p align="center">Let's build the future of AI-Orchestrated Engineering together.</p>r.</p>
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jean Codogno
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/Makefile ADDED
@@ -0,0 +1,49 @@
1
+ BINARY=specforce
2
+ PREFIX ?= /usr/local
3
+ BINDIR = $(PREFIX)/bin
4
+
5
+ # Go paths
6
+ GOPATH=$(shell go env GOPATH)
7
+ GOBIN=$(GOPATH)/bin
8
+
9
+ build:
10
+ go build -o $(BINARY) src/cmd/specforce/main.go
11
+
12
+ install: build
13
+ install -d $(DESTDIR)$(BINDIR)
14
+ install -m 755 $(BINARY) $(DESTDIR)$(BINDIR)/$(BINARY)
15
+
16
+ uninstall:
17
+ rm -f $(DESTDIR)$(BINDIR)/$(BINARY)
18
+
19
+ test-coverage:
20
+ go test -v -coverprofile=coverage.out ./...
21
+
22
+ test:
23
+ go test ./...
24
+
25
+ lint:
26
+ golangci-lint run ./...
27
+
28
+ security:
29
+ $(GOBIN)/gosec -exclude=G703,G304,G306 -fmt=sarif -out=results.sarif ./...
30
+ $(GOBIN)/govulncheck ./... || true
31
+
32
+ quality:
33
+ $(GOBIN)/gremlins unleash
34
+
35
+ quality-lived:
36
+ $(GOBIN)/gremlins unleash -S l
37
+
38
+ check: lint security test quality
39
+
40
+ bootstrap:
41
+ go install github.com/securego/gosec/v2/cmd/gosec@latest
42
+ go install golang.org/x/vuln/cmd/govulncheck@latest
43
+ go install github.com/go-gremlins/gremlins/cmd/gremlins@latest
44
+
45
+ clean-test:
46
+ rm -rf test-init/.specforce test-init/.agent test-init/.claude test-init/.gemini
47
+ rm -f results.sarif coverage.out
48
+
49
+ .PHONY: build test lint security quality check bootstrap clean-test install uninstall
package/README.md ADDED
@@ -0,0 +1,144 @@
1
+
2
+ <p align="center">
3
+ <a href="https://github.com/jeancodogno/specforce-kit/">
4
+ <picture>
5
+ <img src="assets/logo.png" alt="OpenSpec logo" height="128">
6
+ </picture>
7
+ </a>
8
+ </p>
9
+ <p align="center">Ecosystem for AI-assisted development.</p>
10
+
11
+ # Specforce Kit
12
+
13
+ > **The Orchestration Layer for AI-Native Engineering.**
14
+
15
+ Specforce Kit is a professional-grade framework designed to coordinate AI agents (Claude Code, Cursor, KiloCode) through **Spec-Driven Development (SDD)**. It provides the standardized **Kits**, **Constitution**, and **Orchestration Tools** required to transform AI from a "vibe-based" assistant into a deterministic engineering force.
16
+
17
+ ---
18
+
19
+ ## 🧠 Philosophy
20
+
21
+ In the age of AI, implementation is a commodity, but design is a liability. **Implementation without a specification is strictly forbidden in Specforce.**
22
+
23
+ Spec-Driven Development (SDD) decouples design from implementation. A specification acts as a strict contract between human designers and machine executors. By doing so, we prevent "vibe coding" - the accumulation of ad-hoc, unverified decisions - ensuring your system remains coherent, secure, and maintainable no matter which AI agent writes the code.
24
+
25
+ ---
26
+
27
+ ## 📊 Why use Specforce?
28
+
29
+ AI coding without strict guardrails inevitably leads to "vibe coding": vague prompts, unpredictable outputs, and a rapidly accumulating mountain of technical debt. While other tools attempt to solve this, they often force you into new IDE ecosystems, require heavy setups, or bloat your AI's context window.
30
+
31
+ Specforce is designed to be the **invisible orchestration layer**. It brings predictability, architectural control, and strict verification to your AI workflows, acting as an active state machine rather than just a collection of static templates.
32
+
33
+ ### Key Strengths:
34
+
35
+ - **Segmented Constitution**: Instead of a single massive prompt, rules are broken down into specialized domains (Architecture, UI/UX, Security). The agent only loads the exact context it needs, keeping token costs low and reducing hallucinations.
36
+ - **Dynamic Verification Hooks**: Run tests, linters, or custom scripts automatically before an agent is allowed to mark a task as finished.
37
+ - **Context-Aware Instructions**: Inject specific rules and constraints dynamically based on the artifact or phase the agent is currently working on.
38
+ - **Tool & IDE Agnostic**: Bring Spec-Driven Development directly to your terminal. Works flawlessly with your favorite IDE and CLI-based AI agents (Gemini, Claude, Cursor, KiloCode, etc).
39
+ - **Lightning Fast & Zero Dependencies**: Distributed as a single binary, requiring no heavy Python setups or forced ecosystems to bootstrap your project.
40
+
41
+ ---
42
+
43
+ ## 🤖 Agent Usage (Slash Commands)
44
+
45
+ Specforce interacts seamlessly with your preferred AI agent via simple slash commands. Here is the standard workflow:
46
+
47
+ ### 1. The Constitution (`/spf:constitution`)
48
+ **Command:** `/spf:constitution {project description}`
49
+
50
+ The first step in any project. This generates your project's Constitution, containing all rules, principles, UI/UX guidelines, architecture, security, and agent memory.
51
+ - **Tool Agnostic & Segmented:** Instead of dumping rules into tool-specific files (like `.clauderc` or `.gemini/GEMINI.md`) or keeping everything in context, Specforce maintains its own specialized, segmented memory files. The agent only loads what it needs. You can switch tools (e.g., from Gemini CLI to Claude Code) and the project memory remains completely intact.
52
+ - **Interactive Setup:** Describe your project idea and stack. The agent will ask clarifying questions to help you make foundational decisions.
53
+ - **Flexible:** Run it once to set up, or rerun it anytime to update the constitution. You can use it on brand new ideas or point it at an existing project to analyze and document its current architecture.
54
+
55
+ ### 2. Creating a Spec (`/spf:spec`)
56
+ **Command:** `/spf:spec {description of what to add or modify}`
57
+
58
+ Ready to build? The agent will clarify your requirements and generate three core documents: `requirements.md`, `design.md`, and `tasks.md`.
59
+
60
+ ### 3. Implementation (`/spf:implement`)
61
+ **Command:** `/spf:implement`
62
+
63
+ After you validate the generated spec documents, execute this command. The agent will strictly follow the planned tasks in the spec to implement the feature, ensuring zero drift from the agreed design.
64
+
65
+ ### 4. Archiving (`/spf:archive`)
66
+ **Command:** `/spf:archive`
67
+
68
+ Once implementation is fully complete and verified, this command analyzes what needs to be updated in the project's global Constitution based on the new implementation, and archives the completed spec. It follows standardized **Archiving Instructions** that ensure lessons learned are captured in the project memorial and any project-specific cleanup is performed.
69
+
70
+ ---
71
+
72
+ ## ⚡ Human Touchpoints
73
+
74
+ While Specforce powers your AI agents, humans interact primarily through two terminal commands:
75
+
76
+ ### 1. Project Initialization
77
+ Set up the governance and agent kits for your project.
78
+ ```bash
79
+ specforce init
80
+ ```
81
+
82
+ ### 2. The Console (TUI)
83
+ Launch the command center to monitor project health, spec progress, and agent implementations in real-time.
84
+ ```bash
85
+ specforce console
86
+ ```
87
+
88
+ ---
89
+
90
+ ## 🛠️ Supported AI Agents & Tools
91
+
92
+ Specforce Kit is designed to be tool-agnostic but comes with pre-built kits and native slash command support for the most popular AI coding assistants:
93
+
94
+ - **Gemini CLI** (Google)
95
+ - **Claude Code** (Anthropic)
96
+ - **Qwen** (Alibaba)
97
+ - **Kimi Code** (Moonshot AI)
98
+ - **OpenCode**
99
+ - **KiloCode**
100
+ - **Codex**
101
+ - **Antigravity**
102
+
103
+ *Don't see your favorite tool? We welcome PRs to add new kits!*
104
+
105
+ ---
106
+
107
+ ## 🚀 Getting Started
108
+
109
+ ### Installation
110
+
111
+ **Using NPM (Recommended)**
112
+ ```bash
113
+ npm install -g @specforce/kit
114
+ ```
115
+
116
+ **From Source (Requires Go 1.26+ & Make)**
117
+ ```bash
118
+ git clone https://github.com/jeancodogno/specforce-kit.git
119
+ cd specforce-kit
120
+ make build
121
+ make install
122
+ ```
123
+
124
+ ---
125
+
126
+ ## 📚 Documentation
127
+
128
+ For a deeper dive into Specforce Kit, check out our official documentation:
129
+
130
+ - [Getting Started & Workflow](docs/getting-started.md): Environment setup, first steps, and the recommended Spec-Driven Development lifecycle.
131
+ - [Artifacts](docs/artifacts.md): Details about the generated files (Constitution, Requirements, Design, Tasks).
132
+ - [Configuration](docs/configuration.md): Guide to customize hooks and instructions.
133
+ - [CLI Reference](docs/cli.md): Terminal and slash command usage.
134
+ - [Supported Tools](docs/supported-tools.md): List of natively supported AI agents and coding assistants.
135
+
136
+ ---
137
+
138
+ ## 🤝 Contributing
139
+ We welcome contributions! See our [CONTRIBUTING.md](CONTRIBUTING.md) to learn how to add support for new AI agents or improve existing kits.
140
+
141
+ ---
142
+
143
+ ## 📜 License
144
+ Specforce Kit is released under the **MIT License**. See [LICENSE](LICENSE) for details.
Binary file
Binary file
@@ -0,0 +1,41 @@
1
+ # Specforce Artifacts
2
+
3
+ To efficiently orchestrate AI agents and avoid the accumulation of unnecessary context, Specforce divides the project's knowledge into different documents, known as **Artifacts**.
4
+
5
+ ## 1. Constitution Artifacts (`docs/`)
6
+
7
+ Located in your project's `docs/` directory, these files form the **Global Constitution**. They contain the vital rules of the system:
8
+
9
+ - **`architecture.md`**: Architecture patterns, directory structure, database choices, and data flows.
10
+ - **`engineering.md`**: Developer environment setup, coding standards, testing strategies, and CI/CD pipelines.
11
+ - **`governance.md`**: Project boundaries, non-goals, long-term technical vision, and decision-making processes.
12
+ - **`memorial.md`**: An automated log maintained by the AI agent containing past technical decisions, key learnings, and systemic context accumulated over time.
13
+ - **`principles.md`**: The core philosophy of the team or project, guiding the agent's general decisions.
14
+ - **`security.md`**: Mandatory security practices, password handling, and sensitive data management.
15
+ - **`ui-ux.md`**: (If applicable) Visual patterns, color palette, accessible components, and interface behaviors.
16
+
17
+ These files are not read all at once. Specforce injects specific context into the agent only when it needs to execute a related task.
18
+
19
+ ## 2. Specification Artifacts (`.specforce/specs/<name>/`)
20
+
21
+ When you start a new feature (with `/spf:spec`), the agent creates a focused and temporary "specification package" with the following files:
22
+
23
+ ### `requirements.md`
24
+ The definition of the "What". It contains user stories, acceptance criteria (often using BDD syntax like GIVEN/WHEN/THEN), and business constraints.
25
+
26
+ ### `design.md`
27
+ The definition of the "How". It contains the technical solution diagram, changes to databases or APIs, and the classes that will be created or altered. No final code is written here, only structural planning.
28
+
29
+ ### `tasks.md`
30
+ The atomic "Roadmap". It is the decomposition of `design.md` into actionable technical steps of 5 to 20 minutes. Each task must have a **verification** criterion (e.g., a specific test command the agent will run to prove the task worked).
31
+
32
+ ## 3. The `.specforce/` Directory
33
+
34
+ The root `.specforce/` folder maintains the orchestration state. It should generally not be edited manually, with the exception of the configuration file:
35
+
36
+ - **`config.yaml`**: Where you customize validation hooks and advanced instructions (read more in [Configuration](configuration.md)).
37
+ - **`archive/`**: Where finished specifications are stored after running `/spf:archive`, maintaining the history of the application's technical decisions.
38
+
39
+ ---
40
+
41
+ Maintaining the quality of these artifacts is the best way to ensure the AI produces excellent code.
package/docs/cli.md ADDED
@@ -0,0 +1,73 @@
1
+ # Command Line Interface (CLI)
2
+
3
+ Specforce provides a comprehensive set of terminal commands to manage the software development lifecycle, orchestrate AI agents, and monitor project status.
4
+
5
+ Below is a complete reference of all existing commands in the Specforce CLI.
6
+
7
+ ## Global Commands
8
+
9
+ These commands manage the overall Specforce installation and project initialization.
10
+
11
+ ### `specforce init`
12
+ Initializes a new Specforce project in the current directory. It creates the `.specforce/` state directory and generates default constitution templates inside `docs/`. This is the first command you run when bringing Specforce into an existing or new project.
13
+
14
+ ### `specforce install`
15
+ Handles the global installation of the Specforce framework. This command ensures the `specforce` binary and required assets are correctly set up on your machine.
16
+
17
+ ### `specforce console`
18
+ Launches the **Specforce Console TUI (Text User Interface)**. This is your command center. You can visualize project health, monitor active specifications in real-time, and audit task implementations. It is highly recommended to leave this running in a separate terminal pane while you work.
19
+
20
+ ---
21
+
22
+ ## Constitution Commands
23
+
24
+ Manage the foundational rules and guidelines (the "Constitution") of your project.
25
+
26
+ ### `specforce constitution status`
27
+ Evaluates and displays the completeness status of the project's constitution documents (like `architecture.md`, `security.md`, etc.). It helps ensure the system has enough context for AI agents to work properly.
28
+
29
+ ### `specforce constitution artifact <name>`
30
+ Retrieves the specific context, templates, and injected instructions for a given constitution artifact. This is often used internally by AI agents to fetch the right rules when they need them.
31
+
32
+ ---
33
+
34
+ ## Archive Commands
35
+
36
+ Handle the feature archiving process and instructions.
37
+
38
+ ### `specforce archive instructions`
39
+ Displays the full set of instructions for archiving a feature. This includes the constitution metadata (descriptions of all constitution documents), core archiving rules (like updating the project memorial), and any custom project-specific instructions defined in `config.yaml`. This command is primarily used by AI agents to ensure they follow the correct archiving protocol.
40
+
41
+ ---
42
+
43
+ ## Specification Commands
44
+
45
+ Handle the lifecycle of feature specifications, from inception to archiving.
46
+
47
+ ### `specforce spec init <slug>`
48
+ Scaffolds a new feature directory inside `.specforce/specs/<slug>/` and creates the base templates for `requirements.md`, `design.md`, and `tasks.md`.
49
+
50
+ ### `specforce spec list`
51
+ Displays a high-level list of all currently active feature specifications being worked on.
52
+
53
+ ### `specforce spec status <slug>`
54
+ Reports on the completeness and validation status of a specific feature's artifacts (Requirements, Design, Tasks).
55
+
56
+ ### `specforce spec artifact <name>`
57
+ Retrieves the instructions and templates associated with a specific spec artifact (e.g., `requirements`, `design`, `tasks`). Used by agents to ensure they follow formatting rules and business logic constraints.
58
+
59
+ ### `specforce spec archive <slug>`
60
+ Finalizes and archives a completed feature specification. It moves the spec folder into `.specforce/archive/` and closes the iteration loop.
61
+
62
+ ---
63
+
64
+ ## Implementation Commands
65
+
66
+ Track and update the execution of the atomic tasks defined in a specification.
67
+
68
+ ### `specforce implementation status <slug>`
69
+ Loads and displays the sequential implementation roadmap (from `tasks.md`) for a given feature. It shows which tasks are pending, in-progress, or finished.
70
+
71
+ ### `specforce implementation update <slug> --task <id> --status <status>`
72
+ The heartbeat of the execution phase. This command updates the status of a specific task (e.g., from `pending` to `finished`).
73
+ **Note:** When marking a task as `finished`, Specforce automatically triggers any pre-configured Validation Hooks (like linting and testing) to ensure quality before officially changing the state.
@@ -0,0 +1,50 @@
1
+ # Specforce Configuration
2
+
3
+ Configuring Specforce's internal behavior is done through the `.specforce/config.yaml` file. With it, you add layers of intelligence, security, and standardization that apply invisibly to your AI agents.
4
+
5
+ ## 1. Context-Aware Instructions
6
+
7
+ Instead of repeating rules ("Remember to use BDD") in every prompt, you can configure them to be injected automatically at the exact moment the agent works on a specific artifact.
8
+
9
+ In `config.yaml`:
10
+
11
+ ```yaml
12
+ instructions:
13
+ requirements:
14
+ - "Always use BDD GIVEN/WHEN/THEN syntax for acceptance criteria."
15
+ - "Ensure accessibility is always mentioned if UI is involved."
16
+ design:
17
+ - "Always evaluate security impacts for new API routes."
18
+ implementation:
19
+ - "Do not bypass TypeScript typings. Use Type Guards."
20
+ archive:
21
+ - "Always update the project memorial with lessons learned."
22
+ - "Summarize any technical debt introduced during implementation."
23
+ ```
24
+
25
+ ## 2. Validation Hooks (Quality Gates)
26
+
27
+ Hooks are external commands executed by Specforce before or after a state transition. Their main use is to act as **Quality Gates** to prevent the agent from finishing tasks if the code is inadequate.
28
+
29
+ In `config.yaml`:
30
+
31
+ ```yaml
32
+ hooks:
33
+ on_task_finished:
34
+ - "npm run lint"
35
+ - "npm run test"
36
+ ```
37
+
38
+ ### How does it work?
39
+ 1. The agent attempts to mark a task from its specification as finished.
40
+ 2. Specforce pauses the agent and executes `npm run lint` and `npm run test`.
41
+ 3. **If successful (exit 0):** The task is marked as finished.
42
+ 4. **If failed:** The transition is blocked, and the error log is returned to the agent so it can fix the bug before trying to proceed.
43
+
44
+ ### Essential Tips for Hooks:
45
+ - **Be Fast and Silent:** Use fast and silent commands (`--silent`, `--quiet`).
46
+ - **Filter the Output:** Do not dump thousands of log lines into the agent's context. Use focused tools or filters like `grep` to send only specific errors. Example: `golangci-lint run --out-format=line-number` or `npm run test --silent | grep -A 10 "FAIL"`.
47
+
48
+ ---
49
+
50
+ By combining *Context-Aware Instructions* and *Validation Hooks*, you create an unbreakable "guardrail" for your team and your AI agents.