@jeancodogno/specforce-kit 0.1.4 → 0.1.6

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 (151) hide show
  1. package/index.js +0 -0
  2. package/package.json +12 -28
  3. package/.geminiignore +0 -15
  4. package/.github/workflows/ci.yml +0 -101
  5. package/.github/workflows/release.yml +0 -51
  6. package/.golangci.yml +0 -17
  7. package/.goreleaser.yaml +0 -39
  8. package/.rgignore +0 -13
  9. package/.specforce/config.yaml +0 -32
  10. package/.specforce/docs/.gitkeep +0 -0
  11. package/.specforce/docs/architecture.md +0 -98
  12. package/.specforce/docs/engineering.md +0 -80
  13. package/.specforce/docs/governance.md +0 -30
  14. package/.specforce/docs/memorial.md +0 -44
  15. package/.specforce/docs/principles.md +0 -31
  16. package/.specforce/docs/security.md +0 -31
  17. package/.specforce/docs/ui-ux.md +0 -129
  18. package/.specforce/specs/.gitkeep +0 -0
  19. package/AGENTS.md +0 -36
  20. package/CONTRIBUTING.md +0 -81
  21. package/Makefile +0 -49
  22. package/assets/logo-header.png +0 -0
  23. package/assets/logo.png +0 -0
  24. package/docs/artifacts.md +0 -41
  25. package/docs/cli.md +0 -73
  26. package/docs/configuration.md +0 -50
  27. package/docs/getting-started.md +0 -110
  28. package/docs/supported-tools.md +0 -14
  29. package/go.mod +0 -35
  30. package/go.sum +0 -61
  31. package/src/cmd/specforce/main.go +0 -23
  32. package/src/cmd/specforce/main_test.go +0 -7
  33. package/src/internal/agent/artifacts/constitution/architecture.yaml +0 -70
  34. package/src/internal/agent/artifacts/constitution/engineering.yaml +0 -52
  35. package/src/internal/agent/artifacts/constitution/governance.yaml +0 -41
  36. package/src/internal/agent/artifacts/constitution/memorial.yaml +0 -55
  37. package/src/internal/agent/artifacts/constitution/principles.yaml +0 -54
  38. package/src/internal/agent/artifacts/constitution/security.yaml +0 -47
  39. package/src/internal/agent/artifacts/constitution/ui-ux.yaml +0 -158
  40. package/src/internal/agent/artifacts/spec/design.yaml +0 -50
  41. package/src/internal/agent/artifacts/spec/requirements.yaml +0 -48
  42. package/src/internal/agent/artifacts/spec/tasks.yaml +0 -55
  43. package/src/internal/agent/compatibility_test.go +0 -120
  44. package/src/internal/agent/cwd_test.go +0 -9
  45. package/src/internal/agent/embed.go +0 -19
  46. package/src/internal/agent/integration_test.go +0 -138
  47. package/src/internal/agent/kit/agents/product-analyst.yaml +0 -31
  48. package/src/internal/agent/kit/agents/technical-developer.yaml +0 -28
  49. package/src/internal/agent/kit/agents/technical-project-planner.yaml +0 -30
  50. package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +0 -36
  51. package/src/internal/agent/kit/agents/technical-solution-architect.yaml +0 -32
  52. package/src/internal/agent/kit/commands/archive.yaml +0 -25
  53. package/src/internal/agent/kit/commands/constitution.yaml +0 -132
  54. package/src/internal/agent/kit/commands/implement.yaml +0 -96
  55. package/src/internal/agent/kit/commands/spec.yaml +0 -94
  56. package/src/internal/agent/kit/instructions/archive.md +0 -68
  57. package/src/internal/agent/kit/kit.yaml +0 -111
  58. package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +0 -56
  59. package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +0 -58
  60. package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +0 -38
  61. package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +0 -52
  62. package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +0 -137
  63. package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +0 -103
  64. package/src/internal/agent/kit_manifests_test.go +0 -58
  65. package/src/internal/agent/manifest.go +0 -15
  66. package/src/internal/agent/registry.go +0 -69
  67. package/src/internal/agent/registry_test.go +0 -51
  68. package/src/internal/agent/translator.go +0 -334
  69. package/src/internal/agent/translator_test.go +0 -734
  70. package/src/internal/cli/archive.go +0 -91
  71. package/src/internal/cli/archive_test.go +0 -67
  72. package/src/internal/cli/cli.go +0 -259
  73. package/src/internal/cli/cli_test.go +0 -130
  74. package/src/internal/cli/cobra/archive.go +0 -26
  75. package/src/internal/cli/cobra/console.go +0 -21
  76. package/src/internal/cli/cobra/constitution.go +0 -44
  77. package/src/internal/cli/cobra/dummy_test.go +0 -7
  78. package/src/internal/cli/cobra/implementation.go +0 -50
  79. package/src/internal/cli/cobra/init.go +0 -23
  80. package/src/internal/cli/cobra/install.go +0 -21
  81. package/src/internal/cli/cobra/root.go +0 -47
  82. package/src/internal/cli/cobra/spec.go +0 -91
  83. package/src/internal/cli/console.go +0 -48
  84. package/src/internal/cli/constitution.go +0 -190
  85. package/src/internal/cli/constitution_test.go +0 -50
  86. package/src/internal/cli/implementation.go +0 -153
  87. package/src/internal/cli/implementation_test.go +0 -165
  88. package/src/internal/cli/spec.go +0 -369
  89. package/src/internal/cli/spec_test.go +0 -85
  90. package/src/internal/constitution/registry.go +0 -139
  91. package/src/internal/constitution/registry_test.go +0 -97
  92. package/src/internal/constitution/status.go +0 -70
  93. package/src/internal/constitution/status_test.go +0 -160
  94. package/src/internal/core/blueprint.go +0 -49
  95. package/src/internal/core/blueprint_test.go +0 -58
  96. package/src/internal/core/config.go +0 -124
  97. package/src/internal/core/config_test.go +0 -145
  98. package/src/internal/core/constants.go +0 -13
  99. package/src/internal/core/errors.go +0 -31
  100. package/src/internal/core/errors_test.go +0 -48
  101. package/src/internal/core/hooks.go +0 -89
  102. package/src/internal/core/hooks_test.go +0 -51
  103. package/src/internal/core/kit.go +0 -15
  104. package/src/internal/core/kit_test.go +0 -65
  105. package/src/internal/core/path.go +0 -115
  106. package/src/internal/core/path_test.go +0 -101
  107. package/src/internal/core/ui.go +0 -19
  108. package/src/internal/installer/dependencies.go +0 -23
  109. package/src/internal/installer/install.go +0 -89
  110. package/src/internal/installer/installer.go +0 -45
  111. package/src/internal/installer/installer_test.go +0 -96
  112. package/src/internal/project/agents_md.go +0 -108
  113. package/src/internal/project/agents_md_test.go +0 -101
  114. package/src/internal/project/bootstrapper.go +0 -64
  115. package/src/internal/project/bootstrapper_test.go +0 -89
  116. package/src/internal/project/detector.go +0 -35
  117. package/src/internal/project/detector_test.go +0 -96
  118. package/src/internal/project/refresh_integration_test.go +0 -86
  119. package/src/internal/project/service.go +0 -93
  120. package/src/internal/project/service_test.go +0 -135
  121. package/src/internal/spec/archive.go +0 -49
  122. package/src/internal/spec/archive_test.go +0 -55
  123. package/src/internal/spec/discovery.go +0 -53
  124. package/src/internal/spec/discovery_test.go +0 -60
  125. package/src/internal/spec/implementation.go +0 -296
  126. package/src/internal/spec/implementation_test.go +0 -253
  127. package/src/internal/spec/registry.go +0 -142
  128. package/src/internal/spec/registry_test.go +0 -105
  129. package/src/internal/spec/scanner.go +0 -219
  130. package/src/internal/spec/scanner_test.go +0 -243
  131. package/src/internal/spec/service.go +0 -157
  132. package/src/internal/spec/service_test.go +0 -238
  133. package/src/internal/spec/status.go +0 -94
  134. package/src/internal/spec/status_test.go +0 -146
  135. package/src/internal/spec/tasks.go +0 -103
  136. package/src/internal/spec/tasks_test.go +0 -137
  137. package/src/internal/tui/components.go +0 -132
  138. package/src/internal/tui/console.go +0 -247
  139. package/src/internal/tui/console_test.go +0 -19
  140. package/src/internal/tui/constitution.go +0 -36
  141. package/src/internal/tui/constitution_test.go +0 -32
  142. package/src/internal/tui/implementation.go +0 -151
  143. package/src/internal/tui/logo.go +0 -89
  144. package/src/internal/tui/multiselect.go +0 -199
  145. package/src/internal/tui/progressbar.go +0 -37
  146. package/src/internal/tui/progressbar_test.go +0 -30
  147. package/src/internal/tui/spec.go +0 -35
  148. package/src/internal/tui/spinner.go +0 -66
  149. package/src/internal/tui/terminal.go +0 -18
  150. package/src/internal/tui/theme.go +0 -125
  151. package/src/internal/tui/ui.go +0 -52
@@ -1,129 +0,0 @@
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 DELETED
@@ -1,36 +0,0 @@
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
-
package/CONTRIBUTING.md DELETED
@@ -1,81 +0,0 @@
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/Makefile DELETED
@@ -1,49 +0,0 @@
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 ./... > /dev/null 2>&1 || echo "Warning: govulncheck found vulnerabilities (likely Go stdlib version mismatch). Ignored locally."
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
Binary file
package/assets/logo.png DELETED
Binary file
package/docs/artifacts.md DELETED
@@ -1,41 +0,0 @@
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 DELETED
@@ -1,73 +0,0 @@
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.
@@ -1,50 +0,0 @@
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.
@@ -1,110 +0,0 @@
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 i -g @jeancodogno/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.
@@ -1,14 +0,0 @@
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 DELETED
@@ -1,35 +0,0 @@
1
- module github.com/jeancodogno/specforce-kit
2
-
3
- go 1.26.2
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.2 // 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
- )