@jeancodogno/specforce-kit-darwin-arm64 0.1.8 → 0.2.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 (3) hide show
  1. package/README.md +172 -0
  2. package/bin/specforce +0 -0
  3. package/package.json +5 -1
package/README.md ADDED
@@ -0,0 +1,172 @@
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
+ - **Git Worktree Support**: Natively discover and view specifications across multiple git branches simultaneously without switching contexts.
38
+ - **Context-Aware Instructions**: Inject specific rules and constraints dynamically based on the artifact or phase the agent is currently working on.
39
+ - **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).
40
+ - **Lightning Fast & Zero Dependencies**: Distributed as a single binary, requiring no heavy Python setups or forced ecosystems to bootstrap your project.
41
+
42
+ ---
43
+
44
+ ## 🤖 Agent Usage (Slash Commands)
45
+
46
+ Specforce interacts seamlessly with your preferred AI agent via simple slash commands. Here is the standard workflow:
47
+
48
+ ### 1. Discovery (`/spf:discovery`)
49
+ **Command:** `/spf:discovery {idea or bug report}`
50
+
51
+ The early exploration phase. Use this to brainstorm new features or investigate technical issues without modifying any files.
52
+ - **Read-Only Exploration:** The agent is strictly forbidden from writing code or artifacts. It focuses on research, root cause analysis, and technical strategy.
53
+ - **Expert Personas:** Automatically switches between "Senior Product Architect" (Brainstorming) and "Senior Systems Engineer" (Detective) based on your input.
54
+ - **Project Alignment:** Reads your project's Constitution (`.specforce/docs/`) to ensure all ideas align with your principles and architecture.
55
+
56
+ ### 2. The Constitution (`/spf:constitution`)
57
+ **Command:** `/spf:constitution {project description}`
58
+
59
+ The first step in any project. This generates your project's Constitution, containing all rules, principles, UI/UX guidelines, architecture, security, and agent memory.
60
+ - **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.
61
+ - **Interactive Setup:** Describe your project idea and stack. The agent will ask clarifying questions to help you make foundational decisions.
62
+ - **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.
63
+
64
+ ### 2. Creating a Spec (`/spf:spec`)
65
+ **Command:** `/spf:spec {description of what to add or modify}`
66
+
67
+ Ready to build? The agent will clarify your requirements and generate three core documents: `requirements.md`, `design.md`, and `tasks.md`.
68
+
69
+ ### 3. Implementation (`/spf:implement`)
70
+ **Command:** `/spf:implement`
71
+
72
+ 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.
73
+
74
+ ### 4. Archiving (`/spf:archive`)
75
+ **Command:** `/spf:archive`
76
+
77
+ 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.
78
+
79
+ ---
80
+
81
+ ## ⚡ Human Touchpoints
82
+
83
+ While Specforce powers your AI agents, humans interact primarily through two terminal commands:
84
+
85
+ ### 1. Project Initialization
86
+ Set up the governance and agent kits for your project.
87
+ ```bash
88
+ specforce init
89
+ ```
90
+
91
+ ### 2. The Console (TUI)
92
+ Launch the command center to monitor project health, spec progress, and agent implementations in real-time.
93
+ ```bash
94
+ specforce console
95
+ ```
96
+
97
+ ---
98
+
99
+ ## 🛠️ Supported AI Agents & Tools
100
+
101
+ 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:
102
+
103
+ - **Gemini CLI** (Google)
104
+ - **Claude Code** (Anthropic)
105
+ - **Qwen** (Alibaba)
106
+ - **Kimi Code** (Moonshot AI)
107
+ - **OpenCode**
108
+ - **KiloCode**
109
+ - **Codex**
110
+ - **Antigravity**
111
+
112
+ *Don't see your favorite tool? We welcome PRs to add new kits!*
113
+
114
+ ---
115
+
116
+ ## 🚀 Getting Started
117
+
118
+ ### Installation
119
+
120
+ **Using NPM (Recommended)**
121
+ ```bash
122
+ npm i -g @jeancodogno/specforce-kit
123
+ ```
124
+
125
+ **From Source (Requires Go 1.26+ & Make)**
126
+ ```bash
127
+ git clone https://github.com/jeancodogno/specforce-kit.git
128
+ cd specforce-kit
129
+ make build
130
+ make install
131
+ ```
132
+
133
+ ---
134
+
135
+ ## 📚 Documentation
136
+
137
+ For a deeper dive into Specforce Kit, check out our official documentation:
138
+
139
+ - [Getting Started & Workflow](docs/getting-started.md): Environment setup, first steps, and the recommended Spec-Driven Development lifecycle.
140
+ - [Git Worktree Support](docs/git-worktrees.md): Guide to cross-branch specification discovery, unified console, and read-only constraints.
141
+ - [Artifacts](docs/artifacts.md): Details about the generated files (Constitution, Requirements, Design, Tasks).
142
+ - [Configuration](docs/configuration.md): Guide to customize hooks and instructions.
143
+ - [CLI Reference](docs/cli.md): Terminal and slash command usage.
144
+ - [Supported Tools](docs/supported-tools.md): List of natively supported AI agents and coding assistants.
145
+
146
+ ---
147
+
148
+ ## 🔍 Troubleshooting
149
+
150
+ ### "command not found: specforce"
151
+ If you encounter this error after installation, it usually means your npm global bin directory is not in your system's `PATH`.
152
+
153
+ **Fix for macOS/Linux:**
154
+ Add the following line to your shell profile (e.g., `~/.zshrc` or `~/.bashrc`):
155
+ ```bash
156
+ export PATH="$(npm config get prefix)/bin:$PATH"
157
+ ```
158
+
159
+ **Fix for Windows:**
160
+ Ensure that `%AppData%\npm` is in your environment variables.
161
+
162
+ For more detailed troubleshooting, see [Getting Started: Troubleshooting](docs/getting-started.md#troubleshooting).
163
+
164
+ ---
165
+
166
+ ## 🤝 Contributing
167
+ We welcome contributions! See our [CONTRIBUTING.md](CONTRIBUTING.md) to learn how to add support for new AI agents or improve existing kits.
168
+
169
+ ---
170
+
171
+ ## 📜 License
172
+ Specforce Kit is released under the **MIT License**. See [LICENSE](LICENSE) for details.
package/bin/specforce CHANGED
Binary file
package/package.json CHANGED
@@ -1,8 +1,12 @@
1
1
  {
2
2
  "name": "@jeancodogno/specforce-kit-darwin-arm64",
3
- "version": "0.1.8",
3
+ "version": "0.2.0",
4
4
  "description": "Native binary for darwin arm64",
5
5
  "license": "MIT",
6
+ "author": "Jean Codogno <jeancarlo.eng.comp@gmail.com>",
7
+ "repository": { "type": "git", "url": "https://github.com/jeancodogno/specforce-kit.git" },
8
+ "bugs": { "url": "https://github.com/jeancodogno/specforce-kit/issues" },
9
+ "homepage": "https://github.com/jeancodogno/specforce-kit#readme",
6
10
  "os": ["darwin"],
7
11
  "cpu": ["arm64"],
8
12
  "bin": { "specforce": "bin/specforce" }