@jeancodogno/specforce-kit-linux-x64 1.0.0-beta.3 → 1.0.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -39
- package/bin/specforce +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,13 +2,15 @@
|
|
|
2
2
|
<p align="center">
|
|
3
3
|
<a href="https://github.com/jeancodogno/specforce-kit/">
|
|
4
4
|
<picture>
|
|
5
|
-
<
|
|
5
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jeancodogno/specforce-kit/main/assets/brand/lockup-dark-256.png">
|
|
6
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jeancodogno/specforce-kit/main/assets/brand/lockup-light-256.png">
|
|
7
|
+
<img src="https://raw.githubusercontent.com/jeancodogno/specforce-kit/main/assets/brand/app-icon-256.png" alt="Specforce logo" height="128">
|
|
6
8
|
</picture>
|
|
7
9
|
</a>
|
|
8
10
|
</p>
|
|
9
|
-
<p align="center">
|
|
11
|
+
<p align="center">Spec-Driven Development for AI agents.</p>
|
|
10
12
|
|
|
11
|
-
# Specforce
|
|
13
|
+
# Specforce
|
|
12
14
|
|
|
13
15
|
<p align="center">
|
|
14
16
|
<a href="https://github.com/jeancodogno/specforce-kit/releases"><img src="https://img.shields.io/github/v/release/jeancodogno/specforce-kit?style=flat-square" alt="Latest Release"></a>
|
|
@@ -29,13 +31,13 @@
|
|
|
29
31
|
|
|
30
32
|
> **The Orchestration Layer for AI-Native Engineering.**
|
|
31
33
|
|
|
32
|
-
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 **
|
|
34
|
+
Specforce Kit is a professional-grade framework designed to coordinate AI agents (Claude Code, Cursor, Codex, KiloCode and more) through **Spec-Driven Development (SDD)**. It provides the standardized **Skills**, **Constitution**, and **Orchestration Tools** required to transform AI from a "vibe-based" assistant into a deterministic engineering force.
|
|
33
35
|
|
|
34
36
|
---
|
|
35
37
|
|
|
36
38
|
## 🧠 Philosophy
|
|
37
39
|
|
|
38
|
-
In the age of AI, implementation is a commodity, but design is a liability. **Implementation without a specification is strictly forbidden in Specforce.**
|
|
40
|
+
In the age of AI, implementation is a commodity, but design is a liability. **Implementation without a specification is strictly forbidden in Specforce.**
|
|
39
41
|
|
|
40
42
|
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.
|
|
41
43
|
|
|
@@ -50,48 +52,52 @@ Specforce is designed to be the **invisible orchestration layer**. It brings pre
|
|
|
50
52
|
### Key Strengths:
|
|
51
53
|
|
|
52
54
|
- **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.
|
|
55
|
+
- **Sized Specs & Module Deltas**: Small changes need only a task list; larger ones add requirements, design and a delta that keeps the module living specs up to date.
|
|
56
|
+
- **Independent QA**: After implementation, a tester that wrote no code checks every acceptance criterion; a failed verdict blocks archiving.
|
|
53
57
|
- **Dynamic Verification Hooks**: Run tests, linters, or custom scripts automatically before an agent is allowed to mark a task as finished.
|
|
54
58
|
- **Git Worktree Support**: Natively discover and view specifications across multiple git branches simultaneously without switching contexts.
|
|
55
59
|
- **Context-Aware Instructions**: Inject specific rules and constraints dynamically based on the artifact or phase the agent is currently working on.
|
|
56
|
-
- **Tool
|
|
60
|
+
- **Tool Agnostic**: The Constitution and specs live in `.specforce/`, not in tool-specific files, so you can switch AI tools without losing project context.
|
|
57
61
|
- **Lightning Fast & Zero Dependencies**: Distributed as a single binary, requiring no heavy Python setups or forced ecosystems to bootstrap your project.
|
|
58
62
|
|
|
59
63
|
---
|
|
60
64
|
|
|
61
|
-
## 🤖 Agent Usage (
|
|
65
|
+
## 🤖 Agent Usage (Skills)
|
|
62
66
|
|
|
63
|
-
Specforce
|
|
67
|
+
Specforce installs its skills natively in your AI tool. Ask for a skill by name, in plain language, in your agent's chat; the explicit syntax for each tool is in [Invoking skills](docs/en/supported-tools.md#invoking-skills). Here is the standard lifecycle:
|
|
64
68
|
|
|
65
|
-
### 1.
|
|
66
|
-
**
|
|
69
|
+
### 1. The Constitution (`spf.constitution`)
|
|
70
|
+
**Example:** "Use spf.constitution to set up the constitution: {project description and stack}"
|
|
67
71
|
|
|
68
|
-
The
|
|
69
|
-
- **
|
|
70
|
-
- **Expert Personas:** Automatically switches between "Senior Product Architect" (Brainstorming) and "Senior Systems Engineer" (Detective) based on your input.
|
|
71
|
-
- **Project Alignment:** Reads your project's Constitution (`.specforce/docs/`) to ensure all ideas align with your principles and architecture.
|
|
72
|
-
|
|
73
|
-
### 2. The Constitution (`/spf:constitution`)
|
|
74
|
-
**Command:** `/spf:constitution {project description}`
|
|
75
|
-
|
|
76
|
-
The first step in any project. This generates your project's Constitution, containing all rules, principles, UI/UX guidelines, architecture, security, and domain module specifications.
|
|
77
|
-
- **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 specification files. The agent only loads what it needs. You can switch tools (e.g., from Gemini CLI to Claude Code) and the project context remains completely intact.
|
|
72
|
+
The first step in any project. This generates your project's Constitution in `.specforce/docs/`: principles, architecture, UI/UX, security, engineering, governance and domain module specifications (`modules/`).
|
|
73
|
+
- **Segmented:** Specforce keeps its own specialized documents instead of tool-specific rule files. The agent only loads what it needs, and the context stays intact when you switch tools.
|
|
78
74
|
- **Interactive Setup:** Describe your project idea and stack. The agent will ask clarifying questions to help you make foundational decisions.
|
|
79
75
|
- **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.
|
|
80
76
|
|
|
81
|
-
### 2.
|
|
82
|
-
**
|
|
77
|
+
### 2. Discovery (`spf.discovery`)
|
|
78
|
+
**Example:** "Use spf.discovery to investigate: {idea or bug report}"
|
|
79
|
+
|
|
80
|
+
The exploration phase. Use this to brainstorm new features or investigate technical issues before committing to a plan.
|
|
81
|
+
- **Read-Only for Product Code:** The agent never edits your existing files. Disposable evidence (tests, scripts, screenshots) lives in `.specforce/scratch/`.
|
|
82
|
+
- **Consultative:** The agent gives opinions, trade-offs and recommended picks, and finds root causes for bugs.
|
|
83
|
+
- **Formalization:** When you are ready, ask it to formalize the result into a proposal that planning reuses.
|
|
84
|
+
|
|
85
|
+
### 3. Creating a Spec (`spf.spec`)
|
|
86
|
+
**Example:** "Use spf.spec to plan: {description of what to add or modify}"
|
|
87
|
+
|
|
88
|
+
Ready to build? The agent clarifies your requirements and writes the artifacts required by the spec size: `requirements.md`, `design.md`, `tasks.md` and the module deltas. You review and approve them.
|
|
83
89
|
|
|
84
|
-
|
|
90
|
+
### 4. Implementation (`spf.implement`)
|
|
91
|
+
**Example:** "Use spf.implement to implement {spec}"
|
|
85
92
|
|
|
86
|
-
|
|
87
|
-
**Command:** `/spf:implement`
|
|
93
|
+
After you approve the spec, the agent strictly follows the planned tasks, runs your verification hooks, and finishes with an independent QA step that records a verdict for every acceptance criterion.
|
|
88
94
|
|
|
89
|
-
|
|
95
|
+
### 5. Archiving (`spf.archive`)
|
|
96
|
+
**Example:** "Use spf.archive to archive {spec}"
|
|
90
97
|
|
|
91
|
-
|
|
92
|
-
**Command:** `/spf:archive`
|
|
98
|
+
Once implementation is complete and verified, the agent applies the module deltas to the living specs (`.specforce/docs/modules/`), updates the Constitution if needed, and archives the spec. Archiving is refused while tasks are pending, the delta is not applied, or QA failed.
|
|
93
99
|
|
|
94
|
-
|
|
100
|
+
For workflows and tips covering bugs, resizing, changes after implementation, failed QA and other edge cases, see [Workflows & Tips](docs/en/workflows.md).
|
|
95
101
|
|
|
96
102
|
---
|
|
97
103
|
|
|
@@ -100,7 +106,7 @@ Once implementation is fully complete and verified, this command synthesizes dom
|
|
|
100
106
|
While Specforce powers your AI agents, humans interact primarily through two terminal commands:
|
|
101
107
|
|
|
102
108
|
### 1. Project Initialization
|
|
103
|
-
Set up the governance and agent
|
|
109
|
+
Set up the governance and agent skills for your project.
|
|
104
110
|
```bash
|
|
105
111
|
specforce init
|
|
106
112
|
```
|
|
@@ -115,9 +121,8 @@ specforce console
|
|
|
115
121
|
|
|
116
122
|
## 🛠️ Supported AI Agents & Tools
|
|
117
123
|
|
|
118
|
-
Specforce Kit is designed to be tool-agnostic
|
|
124
|
+
Specforce Kit is designed to be tool-agnostic and installs its skills natively for the most popular AI coding assistants:
|
|
119
125
|
|
|
120
|
-
- **Gemini CLI** (Google)
|
|
121
126
|
- **Claude Code** (Anthropic)
|
|
122
127
|
- **Qwen** (Alibaba)
|
|
123
128
|
- **Kimi Code** (Moonshot AI)
|
|
@@ -125,6 +130,7 @@ Specforce Kit is designed to be tool-agnostic but comes with pre-built kits and
|
|
|
125
130
|
- **KiloCode**
|
|
126
131
|
- **Codex**
|
|
127
132
|
- **Antigravity**
|
|
133
|
+
- **Cursor**
|
|
128
134
|
|
|
129
135
|
*Don't see your favorite tool? We welcome PRs to add new kits!*
|
|
130
136
|
|
|
@@ -139,12 +145,12 @@ Specforce Kit is designed to be tool-agnostic but comes with pre-built kits and
|
|
|
139
145
|
npm i -g @jeancodogno/specforce-kit
|
|
140
146
|
```
|
|
141
147
|
|
|
142
|
-
**From Source (Requires Go 1.
|
|
148
|
+
**From Source (Requires Go 1.26+ & Make)**
|
|
143
149
|
```bash
|
|
144
150
|
git clone https://github.com/jeancodogno/specforce-kit.git
|
|
145
151
|
cd specforce-kit
|
|
146
152
|
make build
|
|
147
|
-
# Binary 'specforce' is created in the root.
|
|
153
|
+
# Binary 'specforce' is created in the root.
|
|
148
154
|
# You can move it to your PATH manually or run it from here.
|
|
149
155
|
```
|
|
150
156
|
|
|
@@ -154,12 +160,13 @@ make build
|
|
|
154
160
|
|
|
155
161
|
For a deeper dive into Specforce Kit, check out our official documentation:
|
|
156
162
|
|
|
157
|
-
- [Getting Started & Workflow](docs/en/getting-started.md): Environment setup, first steps, and the recommended Spec-Driven Development lifecycle.
|
|
163
|
+
- [Getting Started & Workflow](docs/en/getting-started.md): Environment setup, first steps, updates, and the recommended Spec-Driven Development lifecycle.
|
|
164
|
+
- [Workflows & Tips](docs/en/workflows.md): Step-by-step workflows, tips and what to do when a step is blocked.
|
|
158
165
|
- [Git Worktree Support](docs/en/git-worktrees.md): Guide to cross-branch specification discovery, unified console, and read-only constraints.
|
|
159
|
-
- [Artifacts](docs/en/artifacts.md):
|
|
166
|
+
- [Artifacts](docs/en/artifacts.md): The generated files (Constitution, Requirements, Design, Tasks), spec sizes, module deltas and the QA report.
|
|
160
167
|
- [Configuration](docs/en/configuration.md): Guide to customize hooks and instructions.
|
|
161
|
-
- [CLI Reference](docs/en/cli.md):
|
|
162
|
-
- [Supported Tools](docs/en/supported-tools.md):
|
|
168
|
+
- [CLI Reference](docs/en/cli.md): Every terminal command and flag.
|
|
169
|
+
- [Supported Tools](docs/en/supported-tools.md): Natively supported AI agents and how to invoke skills in each one.
|
|
163
170
|
|
|
164
171
|
---
|
|
165
172
|
|
|
@@ -187,4 +194,4 @@ We welcome contributions! See our [CONTRIBUTING.md](CONTRIBUTING.md) to learn ho
|
|
|
187
194
|
---
|
|
188
195
|
|
|
189
196
|
## 📜 License
|
|
190
|
-
|
|
197
|
+
Released under the **MIT License**. See [LICENSE](LICENSE) for details.
|
package/bin/specforce
CHANGED
|
Binary file
|