@jeancodogno/specforce-kit 0.1.7 → 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 +29 -1
  2. package/index.js +66 -9
  3. package/package.json +18 -7
package/README.md CHANGED
@@ -34,6 +34,7 @@ Specforce is designed to be the **invisible orchestration layer**. It brings pre
34
34
 
35
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
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.
37
38
  - **Context-Aware Instructions**: Inject specific rules and constraints dynamically based on the artifact or phase the agent is currently working on.
38
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).
39
40
  - **Lightning Fast & Zero Dependencies**: Distributed as a single binary, requiring no heavy Python setups or forced ecosystems to bootstrap your project.
@@ -44,7 +45,15 @@ Specforce is designed to be the **invisible orchestration layer**. It brings pre
44
45
 
45
46
  Specforce interacts seamlessly with your preferred AI agent via simple slash commands. Here is the standard workflow:
46
47
 
47
- ### 1. The Constitution (`/spf:constitution`)
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`)
48
57
  **Command:** `/spf:constitution {project description}`
49
58
 
50
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.
@@ -128,6 +137,7 @@ make install
128
137
  For a deeper dive into Specforce Kit, check out our official documentation:
129
138
 
130
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.
131
141
  - [Artifacts](docs/artifacts.md): Details about the generated files (Constitution, Requirements, Design, Tasks).
132
142
  - [Configuration](docs/configuration.md): Guide to customize hooks and instructions.
133
143
  - [CLI Reference](docs/cli.md): Terminal and slash command usage.
@@ -135,6 +145,24 @@ For a deeper dive into Specforce Kit, check out our official documentation:
135
145
 
136
146
  ---
137
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
+
138
166
  ## 🤝 Contributing
139
167
  We welcome contributions! See our [CONTRIBUTING.md](CONTRIBUTING.md) to learn how to add support for new AI agents or improve existing kits.
140
168
 
package/index.js CHANGED
@@ -24,17 +24,74 @@ try {
24
24
  const binRelativePath = typeof pkgJson.bin === 'string' ? pkgJson.bin : pkgJson.bin.specforce;
25
25
  binaryPath = path.resolve(pkgDir, binRelativePath);
26
26
  } catch (e) {
27
- // Fallback for local development if not in node_modules
28
- const localPkgDir = path.join(__dirname, 'npm', `${platform}-${arch}`);
27
+ // Fallback 1: Look for a binary in the root (built via 'make build' or 'prepare')
28
+ const localBinaryName = platform === 'win32' ? 'specforce.exe' : 'specforce';
29
+ const rootBinaryPath = path.join(__dirname, localBinaryName);
30
+ const fs = require('fs');
31
+
32
+ if (fs.existsSync(rootBinaryPath)) {
33
+ binaryPath = rootBinaryPath;
34
+ } else {
35
+ // Fallback 2: Local development folder structure
36
+ const localPkgDir = path.join(__dirname, 'npm', `${platform}-${arch}`);
37
+ try {
38
+ const pkgJson = require(path.join(localPkgDir, 'package.json'));
39
+ const binRelativePath = typeof pkgJson.bin === 'string' ? pkgJson.bin : pkgJson.bin.specforce;
40
+ binaryPath = path.resolve(localPkgDir, binRelativePath);
41
+ } catch (err) {
42
+ runDiagnostic(platform, arch, pkgName);
43
+ process.exit(1);
44
+ }
45
+ }
46
+ }
47
+
48
+ /**
49
+ * Runs a diagnostic check to help the user fix their environment.
50
+ */
51
+ function runDiagnostic(platform, arch, pkgName) {
52
+ const fs = require('fs');
53
+
54
+ // Aesthetic Colors
55
+ const RESET = "\x1b[0m";
56
+ const BOLD = "\x1b[1m";
57
+ const RED = "\x1b[38;5;196m";
58
+ const MINT = "\x1b[38;5;48m";
59
+ const GRAY = "\x1b[38;5;245m";
60
+
61
+ console.error(`\n${BOLD}${RED}┌── [ SpecForce Diagnostic ] ──────────────────────────┐${RESET}`);
62
+ console.error(`${RED}│${RESET} ${BOLD}Error:${RESET} Native binary for ${platform}-${arch} not found. ${RED}│${RESET}`);
63
+ console.error(`${RED}└──────────────────────────────────────────────────────┘${RESET}`);
64
+
29
65
  try {
30
- const pkgJson = require(path.join(localPkgDir, 'package.json'));
31
- const binRelativePath = typeof pkgJson.bin === 'string' ? pkgJson.bin : pkgJson.bin.specforce;
32
- binaryPath = path.resolve(localPkgDir, binRelativePath);
33
- } catch (err) {
34
- console.error(`[SpecForce] Error: Native binary for ${platform}-${arch} not found.`);
35
- console.error(`Requirement: The package "${pkgName}" must be installed.`);
36
- process.exit(1);
66
+ const npmPrefix = spawnSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf8' }).stdout.trim();
67
+ const binDir = platform === 'win32' ? npmPrefix : path.join(npmPrefix, 'bin');
68
+
69
+ console.error(`\n${BOLD}Target Package:${RESET} ${pkgName}`);
70
+ console.error(`${BOLD}Expected Bin Directory:${RESET} ${binDir}`);
71
+
72
+ if (!process.env.PATH.includes(binDir)) {
73
+ console.error(`\n${BOLD}${MINT}>>> CAUSE DETECTED: PATH MISCONFIGURATION <<<${RESET}`);
74
+ console.error(`${GRAY}Your npm global bin directory is not in your system's PATH.${RESET}\n`);
75
+
76
+ if (platform === 'win32') {
77
+ console.error(`To fix this on Windows, run this in PowerShell as Administrator:`);
78
+ console.error(` ${BOLD}setx /M PATH "%PATH%;${binDir}"${RESET}`);
79
+ } else {
80
+ const shellProfile = process.env.SHELL?.includes('zsh') ? '~/.zshrc' : '~/.bashrc';
81
+ console.error(`To fix this on macOS/Linux, add this to your ${shellProfile}:`);
82
+ console.error(` ${BOLD}export PATH="${binDir}:$PATH"${RESET}`);
83
+ console.error(`\nThen reload your shell: ${BOLD}source ${shellProfile}${RESET}`);
84
+ }
85
+ } else {
86
+ console.error(`\n${BOLD}${MINT}>>> CAUSE DETECTED: MISSING BINARY <<<${RESET}`);
87
+ console.error(`${GRAY}The binary was not found even though your PATH seems correct.${RESET}\n`);
88
+ console.error(`If you are a developer, run: ${BOLD}make build${RESET}`);
89
+ console.error(`Otherwise, try: ${BOLD}npm install -g @jeancodogno/specforce-kit --force${RESET}`);
90
+ }
91
+ } catch (e) {
92
+ console.error(`\n${GRAY}Failed to run full diagnostic. Please ensure 'npm' is installed.${RESET}`);
37
93
  }
94
+ console.error("");
38
95
  }
39
96
 
40
97
  // 3. Execute the binary forwarding all arguments and inheriting stdio
package/package.json CHANGED
@@ -1,23 +1,34 @@
1
1
  {
2
2
  "name": "@jeancodogno/specforce-kit",
3
- "version": "0.1.7",
3
+ "version": "0.2.0",
4
4
  "description": "SpecForce Kit CLI - Distributed via Native Binaries",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "git+https://github.com/jeancodogno/specforce-kit.git"
8
8
  },
9
+ "bugs": {
10
+ "url": "https://github.com/jeancodogno/specforce-kit/issues"
11
+ },
12
+ "homepage": "https://github.com/jeancodogno/specforce-kit#readme",
9
13
  "bin": {
10
14
  "specforce": "index.js"
11
15
  },
16
+ "scripts": {
17
+ "build": "make build",
18
+ "test": "go test ./...",
19
+ "prepare": "make build || true",
20
+ "postinstall": "make build || true"
21
+ },
12
22
  "files": [
13
- "index.js"
23
+ "index.js",
24
+ "LICENSE"
14
25
  ],
15
26
  "optionalDependencies": {
16
- "@jeancodogno/specforce-kit-linux-x64": "0.1.7",
17
- "@jeancodogno/specforce-kit-linux-arm64": "0.1.7",
18
- "@jeancodogno/specforce-kit-darwin-x64": "0.1.7",
19
- "@jeancodogno/specforce-kit-darwin-arm64": "0.1.7",
20
- "@jeancodogno/specforce-kit-win32-x64": "0.1.7"
27
+ "@jeancodogno/specforce-kit-linux-x64": "0.2.0",
28
+ "@jeancodogno/specforce-kit-linux-arm64": "0.2.0",
29
+ "@jeancodogno/specforce-kit-darwin-x64": "0.2.0",
30
+ "@jeancodogno/specforce-kit-darwin-arm64": "0.2.0",
31
+ "@jeancodogno/specforce-kit-win32-x64": "0.2.0"
21
32
  },
22
33
  "author": "Jean Codogno <jeancarlo.eng.comp@gmail.com>",
23
34
  "license": "MIT"