@jeancodogno/specforce-kit 0.1.5 → 0.1.7
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/index.js +46 -0
- package/package.json +12 -28
- package/.geminiignore +0 -15
- package/.github/workflows/ci.yml +0 -104
- package/.github/workflows/release.yml +0 -51
- package/.golangci.yml +0 -24
- package/.goreleaser.yaml +0 -39
- package/.rgignore +0 -13
- package/.specforce/archive/agents-md-hooks-config/design.md +0 -38
- package/.specforce/archive/agents-md-hooks-config/requirements.md +0 -35
- package/.specforce/archive/agents-md-hooks-config/tasks.md +0 -76
- package/.specforce/config.yaml +0 -32
- package/.specforce/docs/.gitkeep +0 -0
- package/.specforce/docs/architecture.md +0 -98
- package/.specforce/docs/engineering.md +0 -84
- package/.specforce/docs/governance.md +0 -30
- package/.specforce/docs/memorial.md +0 -45
- package/.specforce/docs/principles.md +0 -31
- package/.specforce/docs/security.md +0 -31
- package/.specforce/docs/ui-ux.md +0 -129
- package/.specforce/specs/.gitkeep +0 -0
- package/AGENTS.md +0 -46
- package/CONTRIBUTING.md +0 -81
- package/Makefile +0 -49
- package/assets/logo-header.png +0 -0
- package/assets/logo.png +0 -0
- package/docs/artifacts.md +0 -41
- package/docs/cli.md +0 -73
- package/docs/configuration.md +0 -59
- package/docs/getting-started.md +0 -110
- package/docs/supported-tools.md +0 -28
- package/go.mod +0 -35
- package/go.sum +0 -61
- package/src/cmd/specforce/main.go +0 -23
- package/src/cmd/specforce/main_test.go +0 -7
- package/src/internal/agent/artifacts/constitution/architecture.yaml +0 -70
- package/src/internal/agent/artifacts/constitution/engineering.yaml +0 -52
- package/src/internal/agent/artifacts/constitution/governance.yaml +0 -41
- package/src/internal/agent/artifacts/constitution/memorial.yaml +0 -55
- package/src/internal/agent/artifacts/constitution/principles.yaml +0 -54
- package/src/internal/agent/artifacts/constitution/security.yaml +0 -47
- package/src/internal/agent/artifacts/constitution/ui-ux.yaml +0 -158
- package/src/internal/agent/artifacts/spec/design.yaml +0 -50
- package/src/internal/agent/artifacts/spec/requirements.yaml +0 -48
- package/src/internal/agent/artifacts/spec/tasks.yaml +0 -55
- package/src/internal/agent/compatibility_test.go +0 -120
- package/src/internal/agent/cwd_test.go +0 -9
- package/src/internal/agent/embed.go +0 -19
- package/src/internal/agent/integration_test.go +0 -138
- package/src/internal/agent/kit/agents/product-analyst.yaml +0 -31
- package/src/internal/agent/kit/agents/technical-developer.yaml +0 -28
- package/src/internal/agent/kit/agents/technical-project-planner.yaml +0 -30
- package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +0 -36
- package/src/internal/agent/kit/agents/technical-solution-architect.yaml +0 -32
- package/src/internal/agent/kit/commands/archive.yaml +0 -25
- package/src/internal/agent/kit/commands/constitution.yaml +0 -132
- package/src/internal/agent/kit/commands/implement.yaml +0 -96
- package/src/internal/agent/kit/commands/spec.yaml +0 -94
- package/src/internal/agent/kit/instructions/archive.md +0 -68
- package/src/internal/agent/kit/kit.yaml +0 -111
- package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +0 -56
- package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +0 -58
- package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +0 -38
- package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +0 -52
- package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +0 -137
- package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +0 -103
- package/src/internal/agent/kit_manifests_test.go +0 -58
- package/src/internal/agent/manifest.go +0 -15
- package/src/internal/agent/registry.go +0 -69
- package/src/internal/agent/registry_test.go +0 -51
- package/src/internal/agent/translator.go +0 -334
- package/src/internal/agent/translator_test.go +0 -734
- package/src/internal/cli/archive.go +0 -91
- package/src/internal/cli/archive_test.go +0 -67
- package/src/internal/cli/cli.go +0 -259
- package/src/internal/cli/cli_test.go +0 -130
- package/src/internal/cli/cobra/archive.go +0 -26
- package/src/internal/cli/cobra/console.go +0 -21
- package/src/internal/cli/cobra/constitution.go +0 -44
- package/src/internal/cli/cobra/dummy_test.go +0 -7
- package/src/internal/cli/cobra/implementation.go +0 -50
- package/src/internal/cli/cobra/init.go +0 -23
- package/src/internal/cli/cobra/install.go +0 -21
- package/src/internal/cli/cobra/root.go +0 -47
- package/src/internal/cli/cobra/spec.go +0 -91
- package/src/internal/cli/console.go +0 -48
- package/src/internal/cli/constitution.go +0 -190
- package/src/internal/cli/constitution_test.go +0 -50
- package/src/internal/cli/implementation.go +0 -153
- package/src/internal/cli/implementation_test.go +0 -165
- package/src/internal/cli/spec.go +0 -369
- package/src/internal/cli/spec_test.go +0 -85
- package/src/internal/constitution/registry.go +0 -139
- package/src/internal/constitution/registry_test.go +0 -97
- package/src/internal/constitution/status.go +0 -70
- package/src/internal/constitution/status_test.go +0 -160
- package/src/internal/core/blueprint.go +0 -49
- package/src/internal/core/blueprint_test.go +0 -58
- package/src/internal/core/config.go +0 -124
- package/src/internal/core/config_test.go +0 -145
- package/src/internal/core/constants.go +0 -13
- package/src/internal/core/errors.go +0 -31
- package/src/internal/core/errors_test.go +0 -48
- package/src/internal/core/hooks.go +0 -89
- package/src/internal/core/hooks_test.go +0 -51
- package/src/internal/core/kit.go +0 -15
- package/src/internal/core/kit_test.go +0 -65
- package/src/internal/core/path.go +0 -115
- package/src/internal/core/path_test.go +0 -101
- package/src/internal/core/ui.go +0 -19
- package/src/internal/installer/dependencies.go +0 -23
- package/src/internal/installer/install.go +0 -89
- package/src/internal/installer/installer.go +0 -45
- package/src/internal/installer/installer_test.go +0 -96
- package/src/internal/project/agents_md.go +0 -155
- package/src/internal/project/agents_md_test.go +0 -147
- package/src/internal/project/bootstrapper.go +0 -64
- package/src/internal/project/bootstrapper_test.go +0 -89
- package/src/internal/project/detector.go +0 -35
- package/src/internal/project/detector_test.go +0 -96
- package/src/internal/project/refresh_integration_test.go +0 -86
- package/src/internal/project/service.go +0 -93
- package/src/internal/project/service_test.go +0 -135
- package/src/internal/spec/archive.go +0 -49
- package/src/internal/spec/archive_test.go +0 -55
- package/src/internal/spec/discovery.go +0 -53
- package/src/internal/spec/discovery_test.go +0 -60
- package/src/internal/spec/implementation.go +0 -296
- package/src/internal/spec/implementation_test.go +0 -253
- package/src/internal/spec/registry.go +0 -142
- package/src/internal/spec/registry_test.go +0 -105
- package/src/internal/spec/scanner.go +0 -219
- package/src/internal/spec/scanner_test.go +0 -243
- package/src/internal/spec/service.go +0 -157
- package/src/internal/spec/service_test.go +0 -238
- package/src/internal/spec/status.go +0 -94
- package/src/internal/spec/status_test.go +0 -146
- package/src/internal/spec/tasks.go +0 -103
- package/src/internal/spec/tasks_test.go +0 -137
- package/src/internal/tui/components.go +0 -132
- package/src/internal/tui/console.go +0 -247
- package/src/internal/tui/console_test.go +0 -19
- package/src/internal/tui/constitution.go +0 -36
- package/src/internal/tui/constitution_test.go +0 -32
- package/src/internal/tui/implementation.go +0 -151
- package/src/internal/tui/logo.go +0 -89
- package/src/internal/tui/multiselect.go +0 -199
- package/src/internal/tui/progressbar.go +0 -37
- package/src/internal/tui/progressbar_test.go +0 -30
- package/src/internal/tui/spec.go +0 -35
- package/src/internal/tui/spinner.go +0 -66
- package/src/internal/tui/terminal.go +0 -18
- package/src/internal/tui/theme.go +0 -125
- package/src/internal/tui/ui.go +0 -52
package/index.js
CHANGED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
const { spawnSync } = require('child_process');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* SpecForce Kit Proxy
|
|
8
|
+
* Detects the current platform/arch and executes the corresponding native binary.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
const platform = process.platform;
|
|
12
|
+
const arch = process.arch;
|
|
13
|
+
const pkgName = `@jeancodogno/specforce-kit-${platform}-${arch}`;
|
|
14
|
+
|
|
15
|
+
let binaryPath;
|
|
16
|
+
|
|
17
|
+
try {
|
|
18
|
+
// 1. Try to resolve the platform-specific package
|
|
19
|
+
const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
|
|
20
|
+
const pkgDir = path.dirname(pkgJsonPath);
|
|
21
|
+
const pkgJson = require(pkgJsonPath);
|
|
22
|
+
|
|
23
|
+
// 2. Extract binary path from package.json bin field
|
|
24
|
+
const binRelativePath = typeof pkgJson.bin === 'string' ? pkgJson.bin : pkgJson.bin.specforce;
|
|
25
|
+
binaryPath = path.resolve(pkgDir, binRelativePath);
|
|
26
|
+
} catch (e) {
|
|
27
|
+
// Fallback for local development if not in node_modules
|
|
28
|
+
const localPkgDir = path.join(__dirname, 'npm', `${platform}-${arch}`);
|
|
29
|
+
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);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// 3. Execute the binary forwarding all arguments and inheriting stdio
|
|
41
|
+
const result = spawnSync(binaryPath, process.argv.slice(2), {
|
|
42
|
+
stdio: 'inherit'
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
// 4. Propagate the exit code
|
|
46
|
+
process.exit(result.status ?? 0);
|
package/package.json
CHANGED
|
@@ -1,39 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jeancodogno/specforce-kit",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "SpecForce Kit CLI - Distributed via
|
|
3
|
+
"version": "0.1.7",
|
|
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
9
|
"bin": {
|
|
10
|
-
"specforce": "
|
|
10
|
+
"specforce": "index.js"
|
|
11
11
|
},
|
|
12
|
-
"
|
|
13
|
-
"
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
"
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
"
|
|
21
|
-
"path": "./bin",
|
|
22
|
-
"url": "https://github.com/jeancodogno/specforce-kit/releases/download/v{{version}}/specforce-kit_{{platform}}_{{arch}}.tar.gz",
|
|
23
|
-
"platforms": {
|
|
24
|
-
"linux": {
|
|
25
|
-
"x64": "linux_amd64",
|
|
26
|
-
"arm64": "linux_arm64"
|
|
27
|
-
},
|
|
28
|
-
"darwin": {
|
|
29
|
-
"x64": "darwin_amd64",
|
|
30
|
-
"arm64": "darwin_arm64"
|
|
31
|
-
},
|
|
32
|
-
"win32": {
|
|
33
|
-
"x64": "windows_amd64",
|
|
34
|
-
"arm64": "windows_arm64"
|
|
35
|
-
}
|
|
36
|
-
}
|
|
12
|
+
"files": [
|
|
13
|
+
"index.js"
|
|
14
|
+
],
|
|
15
|
+
"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"
|
|
37
21
|
},
|
|
38
22
|
"author": "Jean Codogno <jeancarlo.eng.comp@gmail.com>",
|
|
39
23
|
"license": "MIT"
|
package/.geminiignore
DELETED
package/.github/workflows/ci.yml
DELETED
|
@@ -1,104 +0,0 @@
|
|
|
1
|
-
name: CI
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
push:
|
|
5
|
-
branches: [ main ]
|
|
6
|
-
pull_request:
|
|
7
|
-
branches: [ main ]
|
|
8
|
-
|
|
9
|
-
permissions:
|
|
10
|
-
contents: read
|
|
11
|
-
security-events: write
|
|
12
|
-
|
|
13
|
-
jobs:
|
|
14
|
-
lint:
|
|
15
|
-
name: Lint
|
|
16
|
-
runs-on: ubuntu-latest
|
|
17
|
-
steps:
|
|
18
|
-
- name: Checkout code
|
|
19
|
-
uses: actions/checkout@v4
|
|
20
|
-
|
|
21
|
-
- name: Setup Go
|
|
22
|
-
uses: actions/setup-go@v5
|
|
23
|
-
with:
|
|
24
|
-
go-version: "1.26.2"
|
|
25
|
-
cache: true
|
|
26
|
-
|
|
27
|
-
- name: golangci-lint
|
|
28
|
-
uses: golangci/golangci-lint-action@v9
|
|
29
|
-
with:
|
|
30
|
-
version: latest
|
|
31
|
-
verify: false
|
|
32
|
-
args: --timeout=5m
|
|
33
|
-
install-mode: goinstall
|
|
34
|
-
skip-pkg-cache: true
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
security:
|
|
38
|
-
name: Security
|
|
39
|
-
runs-on: ubuntu-latest
|
|
40
|
-
steps:
|
|
41
|
-
- name: Checkout code
|
|
42
|
-
uses: actions/checkout@v4
|
|
43
|
-
|
|
44
|
-
- name: Setup Go
|
|
45
|
-
uses: actions/setup-go@v5
|
|
46
|
-
with:
|
|
47
|
-
go-version: "1.26.2"
|
|
48
|
-
cache: true
|
|
49
|
-
|
|
50
|
-
- name: Bootstrap Tools
|
|
51
|
-
run: make bootstrap
|
|
52
|
-
|
|
53
|
-
- name: Run Security Scans
|
|
54
|
-
run: make security
|
|
55
|
-
continue-on-error: true # Upload SARIF even if findings exist
|
|
56
|
-
|
|
57
|
-
- name: Upload SARIF
|
|
58
|
-
uses: github/codeql-action/upload-sarif@v3
|
|
59
|
-
with:
|
|
60
|
-
sarif_file: results.sarif
|
|
61
|
-
|
|
62
|
-
test:
|
|
63
|
-
name: Unit Tests
|
|
64
|
-
runs-on: ubuntu-latest
|
|
65
|
-
steps:
|
|
66
|
-
- name: Checkout code
|
|
67
|
-
uses: actions/checkout@v4
|
|
68
|
-
|
|
69
|
-
- name: Setup Go
|
|
70
|
-
uses: actions/setup-go@v5
|
|
71
|
-
with:
|
|
72
|
-
go-version: "1.26.2"
|
|
73
|
-
cache: true
|
|
74
|
-
|
|
75
|
-
- name: Run Tests
|
|
76
|
-
run: make test-coverage
|
|
77
|
-
|
|
78
|
-
- name: Check Coverage
|
|
79
|
-
run: |
|
|
80
|
-
CORE_COVERAGE=$(go tool cover -func=coverage.out | grep -E "src/internal/(core|project|spec)" | awk '{count++; sum+=$3} END {print sum/count}' | tr ',' '.')
|
|
81
|
-
echo "Core Packages Average Coverage: $CORE_COVERAGE%"
|
|
82
|
-
if (( $(echo "$CORE_COVERAGE < 80" | bc -l) )); then
|
|
83
|
-
echo "Core coverage is below 80%"
|
|
84
|
-
exit 1
|
|
85
|
-
fi
|
|
86
|
-
|
|
87
|
-
quality:
|
|
88
|
-
name: Mutation Quality
|
|
89
|
-
runs-on: ubuntu-latest
|
|
90
|
-
steps:
|
|
91
|
-
- name: Checkout code
|
|
92
|
-
uses: actions/checkout@v4
|
|
93
|
-
|
|
94
|
-
- name: Setup Go
|
|
95
|
-
uses: actions/setup-go@v5
|
|
96
|
-
with:
|
|
97
|
-
go-version: "1.26.2"
|
|
98
|
-
cache: true
|
|
99
|
-
|
|
100
|
-
- name: Bootstrap Tools
|
|
101
|
-
run: make bootstrap
|
|
102
|
-
|
|
103
|
-
- name: Run Mutation Tests
|
|
104
|
-
run: make quality
|
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
name: Release
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
push:
|
|
5
|
-
tags:
|
|
6
|
-
- 'v*'
|
|
7
|
-
|
|
8
|
-
permissions:
|
|
9
|
-
contents: write
|
|
10
|
-
|
|
11
|
-
jobs:
|
|
12
|
-
goreleaser:
|
|
13
|
-
runs-on: ubuntu-latest
|
|
14
|
-
steps:
|
|
15
|
-
- name: Checkout
|
|
16
|
-
uses: actions/checkout@v4
|
|
17
|
-
with:
|
|
18
|
-
fetch-depth: 0
|
|
19
|
-
|
|
20
|
-
- name: Set up Go
|
|
21
|
-
uses: actions/setup-go@v5
|
|
22
|
-
with:
|
|
23
|
-
go-version: "1.26.2"
|
|
24
|
-
cache: true
|
|
25
|
-
|
|
26
|
-
- name: Run GoReleaser
|
|
27
|
-
uses: goreleaser/goreleaser-action@v6
|
|
28
|
-
with:
|
|
29
|
-
distribution: goreleaser
|
|
30
|
-
version: latest
|
|
31
|
-
args: release --clean
|
|
32
|
-
env:
|
|
33
|
-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
34
|
-
|
|
35
|
-
npm-publish:
|
|
36
|
-
needs: goreleaser
|
|
37
|
-
runs-on: ubuntu-latest
|
|
38
|
-
steps:
|
|
39
|
-
- name: Checkout
|
|
40
|
-
uses: actions/checkout@v4
|
|
41
|
-
|
|
42
|
-
- name: Set up Node
|
|
43
|
-
uses: actions/setup-node@v4
|
|
44
|
-
with:
|
|
45
|
-
node-version: '20'
|
|
46
|
-
registry-url: 'https://registry.npmjs.org'
|
|
47
|
-
|
|
48
|
-
- name: Publish to NPM
|
|
49
|
-
run: npm publish --access public
|
|
50
|
-
env:
|
|
51
|
-
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
package/.golangci.yml
DELETED
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
# Arquivo: .golangci.yml
|
|
2
|
-
version: 2
|
|
3
|
-
|
|
4
|
-
run:
|
|
5
|
-
concurrency: 4
|
|
6
|
-
timeout: 5m
|
|
7
|
-
issues-exit-code: 1
|
|
8
|
-
tests: true
|
|
9
|
-
|
|
10
|
-
linters:
|
|
11
|
-
enable:
|
|
12
|
-
- gocyclo
|
|
13
|
-
- gocognit
|
|
14
|
-
- funlen
|
|
15
|
-
- dupl
|
|
16
|
-
|
|
17
|
-
linters-settings:
|
|
18
|
-
gocyclo:
|
|
19
|
-
min-complexity: 35
|
|
20
|
-
gocognit:
|
|
21
|
-
min-complexity: 35
|
|
22
|
-
funlen:
|
|
23
|
-
lines: 120
|
|
24
|
-
statements: 60
|
package/.goreleaser.yaml
DELETED
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
# .goreleaser.yaml
|
|
2
|
-
version: 2
|
|
3
|
-
project_name: specforce-kit
|
|
4
|
-
|
|
5
|
-
before:
|
|
6
|
-
hooks:
|
|
7
|
-
- go mod tidy
|
|
8
|
-
|
|
9
|
-
builds:
|
|
10
|
-
- env:
|
|
11
|
-
- CGO_ENABLED=0
|
|
12
|
-
goos:
|
|
13
|
-
- linux
|
|
14
|
-
- windows
|
|
15
|
-
- darwin
|
|
16
|
-
goarch:
|
|
17
|
-
- amd64
|
|
18
|
-
- arm64
|
|
19
|
-
main: ./src/cmd/specforce/main.go
|
|
20
|
-
binary: specforce
|
|
21
|
-
ldflags:
|
|
22
|
-
- -s -w -X main.version={{.Version}}
|
|
23
|
-
|
|
24
|
-
archives:
|
|
25
|
-
- format: tar.gz
|
|
26
|
-
name_template: "{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}"
|
|
27
|
-
|
|
28
|
-
checksum:
|
|
29
|
-
name_template: "checksums.txt"
|
|
30
|
-
|
|
31
|
-
snapshot:
|
|
32
|
-
name_template: "{{ .Tag }}-next"
|
|
33
|
-
|
|
34
|
-
changelog:
|
|
35
|
-
sort: asc
|
|
36
|
-
filters:
|
|
37
|
-
exclude:
|
|
38
|
-
- "^docs:"
|
|
39
|
-
- "^test:"
|
package/.rgignore
DELETED
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
slug: agents-md-hooks-config
|
|
3
|
-
lens: Backend-heavy
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Technical Design: AGENTS.md Hooks and Platform Configuration
|
|
7
|
-
|
|
8
|
-
## 1. Architecture Blueprint
|
|
9
|
-
|
|
10
|
-
```mermaid
|
|
11
|
-
graph TB
|
|
12
|
-
CLI[Specforce CLI] --> Service[Project Service]
|
|
13
|
-
Service --> AgentsMD[agents_md.go]
|
|
14
|
-
AgentsMD --> Template[agentsMDTemplate]
|
|
15
|
-
AgentsMD --> Configs[Ensure Platform Configs]
|
|
16
|
-
Configs --> Gemini[.gemini/settings.json]
|
|
17
|
-
Configs --> Antigravity[.agent/rules/AGENTS.md symlink]
|
|
18
|
-
Configs --> Claude[.claude/rules/AGENTS.md symlink]
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
## 2. API & Interfaces (The Contract)
|
|
22
|
-
|
|
23
|
-
### Internal Template Update
|
|
24
|
-
The `agentsMDTemplate` constant in `src/internal/project/agents_md.go` will be updated to include the correct hook names.
|
|
25
|
-
|
|
26
|
-
### New Functionality
|
|
27
|
-
`EnsureAgentsMD` will be extended to call a new private function `ensurePlatformConfigs(root string) error`.
|
|
28
|
-
|
|
29
|
-
**`ensurePlatformConfigs` Responsibilities:**
|
|
30
|
-
- **Gemini:** Ensure `.gemini/` directory exists. Write `settings.json` with `fileName` as an array: `["AGENTS.md", "GEMINI.md"]`.
|
|
31
|
-
- **Antigravity:** Ensure `.agent/rules/` directory exists. Create relative symlink `AGENTS.md -> ../../AGENTS.md`.
|
|
32
|
-
- **Claude Code:** Ensure `.claude/rules/` directory exists. Create relative symlink `AGENTS.md -> ../../AGENTS.md`.
|
|
33
|
-
|
|
34
|
-
## 3. File & Component Inventory
|
|
35
|
-
|
|
36
|
-
**Backend:**
|
|
37
|
-
- `src/internal/project/agents_md.go` -> Update template and implement `ensurePlatformConfigs`.
|
|
38
|
-
- `src/internal/project/agents_md_test.go` -> Add tests for platform config creation.
|
|
@@ -1,35 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
slug: agents-md-hooks-config
|
|
3
|
-
lens: Backend-heavy
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Feature: AGENTS.md Hooks and Platform Configuration
|
|
7
|
-
|
|
8
|
-
## 1. Context & Value
|
|
9
|
-
The `AGENTS.md` file serves as the primary entry point for AI agents to understand the project's Specforce-driven rules. Currently, the hook examples are outdated. Additionally, Specforce needs to automatically configure environment-specific settings for Gemini, Antigravity, and Claude Code to ensure they can correctly discover and respect the project's rules.
|
|
10
|
-
|
|
11
|
-
## 2. Out of Scope (Anti-Goals)
|
|
12
|
-
- Changing the core hook execution logic in the Specforce binary.
|
|
13
|
-
- Adding support for other AI agents not specified in this request.
|
|
14
|
-
|
|
15
|
-
## 3. Acceptance Criteria (BDD)
|
|
16
|
-
|
|
17
|
-
### [REQ-1] Correct Hook Configuration Examples
|
|
18
|
-
**User Story:** AS A developer, I WANT TO see accurate hook configuration examples in `AGENTS.md`, SO THAT I can correctly configure my project's CI/CD and verification gates.
|
|
19
|
-
|
|
20
|
-
**Scenarios:**
|
|
21
|
-
1. **[Happy Path]** GIVEN the `AGENTS.md` template WHEN it is generated THEN it MUST include `on_task_finished`, `on_phase_finished`, and `on_all_tasks_finished` as hook examples.
|
|
22
|
-
2. **[Outdated Names]** GIVEN the current template WHEN updating THEN `on_task_finish` and `on_spec_finish` MUST be removed or replaced with the correct names.
|
|
23
|
-
|
|
24
|
-
### [REQ-2] Automatic Platform-Specific Configuration
|
|
25
|
-
**User Story:** AS A developer initializing or refreshing a project, I WANT Specforce to automatically set up agent-specific configuration files and links, SO THAT I don't have to perform manual setup for each agent.
|
|
26
|
-
|
|
27
|
-
**Scenarios:**
|
|
28
|
-
1. **[Gemini Config]** GIVEN a project refresh WHEN `EnsureAgentsMD` is called THEN Specforce MUST ensure `.gemini/settings.json` exists with `{ "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }`.
|
|
29
|
-
2. **[Antigravity Link]** GIVEN a project refresh WHEN `EnsureAgentsMD` is called THEN Specforce MUST ensure a symbolic link exists at `.agent/rules/AGENTS.md` pointing to `../../AGENTS.md`.
|
|
30
|
-
3. **[Claude Code Link]** GIVEN a project refresh WHEN `EnsureAgentsMD` is called THEN Specforce MUST ensure a symbolic link exists at `.claude/rules/AGENTS.md` pointing to `../../AGENTS.md`.
|
|
31
|
-
|
|
32
|
-
## 4. Business Invariants
|
|
33
|
-
- The generated `AGENTS.md` MUST always use the `<!-- SPECFORCE_AGENTS_START -->` and `<!-- SPECFORCE_AGENTS_END -->` markers.
|
|
34
|
-
- Hook names in the template MUST exactly match the YAML tags defined in `src/internal/core/config.go`.
|
|
35
|
-
- Symlinks MUST be relative to ensure portability across different environments.
|
|
@@ -1,76 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
slug: agents-md-hooks-config
|
|
3
|
-
lens: Backend-heavy
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Implementation Roadmap: AGENTS.md Hooks and Platform Configuration
|
|
7
|
-
|
|
8
|
-
## 1. Execution Strategy
|
|
9
|
-
- **Gravity Order:** Update Internal Template -> Implement Platform Config Logic -> Update Tests -> Verify -> Update Public Documentation.
|
|
10
|
-
|
|
11
|
-
## 2. Tasks
|
|
12
|
-
|
|
13
|
-
### Phase 1: Template and Core Logic
|
|
14
|
-
|
|
15
|
-
#### T1.1: [CODE] Update AGENTS.md Template Hooks
|
|
16
|
-
**State:** `[FINISHED]`
|
|
17
|
-
**Target:** `src/internal/project/agents_md.go`
|
|
18
|
-
**Context:** [REQ-1]
|
|
19
|
-
|
|
20
|
-
**Action Steps:**
|
|
21
|
-
- Update `agentsMDTemplate` to replace outdated hook names with `on_task_finished`, `on_phase_finished`, `on_all_tasks_finished`.
|
|
22
|
-
|
|
23
|
-
**Verification (TDD):**
|
|
24
|
-
Run `go test ./src/internal/project/...`.
|
|
25
|
-
|
|
26
|
-
#### T1.2: [CODE] Implement ensurePlatformConfigs
|
|
27
|
-
**State:** `[FINISHED]`
|
|
28
|
-
**Target:** `src/internal/project/agents_md.go`
|
|
29
|
-
**Context:** [REQ-2]
|
|
30
|
-
|
|
31
|
-
**Action Steps:**
|
|
32
|
-
- Create `ensurePlatformConfigs(root string) error` helper.
|
|
33
|
-
- Implement Gemini settings creation using an array for `fileName`.
|
|
34
|
-
- Implement Antigravity and Claude Code symlink creation.
|
|
35
|
-
- Call `ensurePlatformConfigs` from `EnsureAgentsMD`.
|
|
36
|
-
|
|
37
|
-
**Verification (TDD):**
|
|
38
|
-
Run `go test ./src/internal/project/...`.
|
|
39
|
-
|
|
40
|
-
### Phase 2: Testing and Verification
|
|
41
|
-
|
|
42
|
-
#### T2.1: [TEST] Add Platform Config Tests
|
|
43
|
-
**State:** `[FINISHED]`
|
|
44
|
-
**Target:** `src/internal/project/agents_md_test.go`
|
|
45
|
-
**Context:** [REQ-2]
|
|
46
|
-
|
|
47
|
-
**Action Steps:**
|
|
48
|
-
- Add test cases to verify `.gemini/settings.json` content.
|
|
49
|
-
- Add test cases to verify symlink existence and targets for `.agent` and `.claude`.
|
|
50
|
-
|
|
51
|
-
**Verification (TDD):**
|
|
52
|
-
Run `go test ./src/internal/project/...` and ensure all tests pass.
|
|
53
|
-
|
|
54
|
-
#### T2.2: [CLI] Verify Final Generation
|
|
55
|
-
**State:** `[FINISHED]`
|
|
56
|
-
**Target:** `Global Scope`
|
|
57
|
-
**Context:** [REQ-1, REQ-2]
|
|
58
|
-
|
|
59
|
-
**Action Steps:**
|
|
60
|
-
- Run `go run src/cmd/specforce/main.go project refresh`.
|
|
61
|
-
- Verify files and symlinks exist in the project root.
|
|
62
|
-
|
|
63
|
-
**Verification (TDD):**
|
|
64
|
-
`ls -l .agent/rules/AGENTS.md` and `cat .gemini/settings.json`.
|
|
65
|
-
|
|
66
|
-
#### T2.3: [DOCS] Update documentation files
|
|
67
|
-
**State:** `[FINISHED]`
|
|
68
|
-
**Target:** `docs/`
|
|
69
|
-
**Context:** [REQ-1, REQ-2]
|
|
70
|
-
|
|
71
|
-
**Action Steps:**
|
|
72
|
-
- Update `docs/configuration.md` with all supported hook names.
|
|
73
|
-
- Update `docs/supported-tools.md` to mention automated platform configuration.
|
|
74
|
-
|
|
75
|
-
**Verification (TDD):**
|
|
76
|
-
Inspect markdown files.
|
package/.specforce/config.yaml
DELETED
|
@@ -1,32 +0,0 @@
|
|
|
1
|
-
instructions:
|
|
2
|
-
# Example: Project-wide instructions for all requirements artifacts
|
|
3
|
-
# requirements:
|
|
4
|
-
# - "Always use BDD GIVEN/WHEN/THEN syntax"
|
|
5
|
-
# - "Ensure accessibility is mentioned for UI components"
|
|
6
|
-
|
|
7
|
-
# Example: Project-wide instructions for all design artifacts
|
|
8
|
-
# design:
|
|
9
|
-
# - "Use Mermaid.js for architecture diagrams"
|
|
10
|
-
# - "Include a detailed component inventory"
|
|
11
|
-
|
|
12
|
-
# Example: Project-wide instructions for all tasks artifacts
|
|
13
|
-
# tasks:
|
|
14
|
-
# - "Each task must have a clear verification step"
|
|
15
|
-
# - "Group tasks by implementation phases"
|
|
16
|
-
|
|
17
|
-
# Example: Project-wide instructions for the implementation phase
|
|
18
|
-
# implementation:
|
|
19
|
-
# - "Always run 'go fmt' before finishing a task"
|
|
20
|
-
# - "Use explicit type casts instead of interfaces when possible"
|
|
21
|
-
# archive:
|
|
22
|
-
# - "Always update the project memorial with lessons learned from the feature"
|
|
23
|
-
|
|
24
|
-
hooks:
|
|
25
|
-
# Example: Run linting and tests automatically when finishing tasks
|
|
26
|
-
on_task_finished:
|
|
27
|
-
- "make lint"
|
|
28
|
-
- "make test"
|
|
29
|
-
# on_phase_finished:
|
|
30
|
-
# - "go test ./src/internal/..."
|
|
31
|
-
# on_all_tasks_finished:
|
|
32
|
-
# - "go test ./..."
|
package/.specforce/docs/.gitkeep
DELETED
|
File without changes
|
|
@@ -1,98 +0,0 @@
|
|
|
1
|
-
# Architecture
|
|
2
|
-
|
|
3
|
-
## Stack & Tooling Baseline
|
|
4
|
-
- **Backend:** Go (1.24.2+)
|
|
5
|
-
- **CLI Framework:** Cobra (for command routing, nested subcommands, and flag parsing)
|
|
6
|
-
- **Frontend:** TUI (Bubbletea, Bubbles, Lipgloss)
|
|
7
|
-
- **State Management:** Functional (Bubbletea Model/Update/View pattern)
|
|
8
|
-
- **Data:** Filesystem (Local `.specforce/` directory, JSON/Markdown/YAML)
|
|
9
|
-
- **Tooling/Infra:** Makefile (with dynamic `GOBIN` detection), Go CLI, Shell
|
|
10
|
-
|
|
11
|
-
## API & Communication Paradigm
|
|
12
|
-
- **Client-to-Server:** CLI/TUI (Internal function calls and direct FS access)
|
|
13
|
-
- **Internal-Services:** Modular Go packages in `src/internal/`
|
|
14
|
-
|
|
15
|
-
## Continuous Integration (CI)
|
|
16
|
-
- **Orchestration:** GitHub Actions.
|
|
17
|
-
- **Workflow Pattern:** Multi-job parallel pipeline to maximize feedback speed.
|
|
18
|
-
- **Security Integration:** Mandatory SARIF upload for security scanning results.
|
|
19
|
-
|
|
20
|
-
## High-Level Architecture (Mermaid)
|
|
21
|
-
```mermaid
|
|
22
|
-
graph TB
|
|
23
|
-
User((User)) -- CLI/TUI Commands --> CLI[CLI Executor]
|
|
24
|
-
CLI -- TUI Views --> User
|
|
25
|
-
CLI -- Call --> Services[Domain Services]
|
|
26
|
-
|
|
27
|
-
Services -- Orchestration --> Agent[Agent/Kit Manager]
|
|
28
|
-
Services -- Management --> Spec[Spec Manager]
|
|
29
|
-
Services -- Management --> Const[Constitution Manager]
|
|
30
|
-
Services -- Progress/Logging --> UI[core.UI]
|
|
31
|
-
|
|
32
|
-
Agent -- Read/Write --> KitFS[Embedded Kit FS]
|
|
33
|
-
Spec -- Read/Write --> SpecFS[Local .specforce/specs/]
|
|
34
|
-
Const -- Read/Write --> ConstFS[Local .specforce/docs/]
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
## Architectural Principles
|
|
38
|
-
1. **Domain Logic Agnostic:** Core logic for managing specs and constitution MUST remain independent of the TUI/CLI framework.
|
|
39
|
-
2. **Service Layer Isolation:** All business logic orchestration MUST be encapsulated in domain-specific Services (e.g., `project.Service`, `spec.Service`). The CLI/TUI layer is restricted to gathering user input and displaying output, delegating all domain operations to these services.
|
|
40
|
-
3. **Embedded vs. Local:** Standard agent kits are embedded in the binary but MAY be overridden by local versions for development.
|
|
41
|
-
3. **File-Driven Truth:** The `.specforce/` directory is the single source of truth for the project's state.
|
|
42
|
-
4. Project Configuration: Global project-level instructions and settings are managed via `.specforce/config.yaml` and loaded into the `core.ProjectConfig` entity.
|
|
43
|
-
5. Automatic Configuration Initialization: To improve discoverability and ease of use, the `specforce init` command MUST automatically generate a default `.specforce/config.yaml` file populated with illustrative examples if it does not already exist.
|
|
44
|
-
6. Strict Typing: All data models (Spec, Constitution, Artifacts) must have rigorous Go struct definitions and schema validation.
|
|
45
|
-
|
|
46
|
-
6. **Metadata-Driven Discovery:** Systems that manage sets of dynamic components (e.g., Agents, Skills) MUST use metadata files (e.g., `manifest.yaml`) for discovery within an `fs.FS`. Hardcoded lists are forbidden to ensure extensibility without recompilation.
|
|
47
|
-
7. **Graceful Lifecycle Management:** The application's lifecycle MUST be controlled by a root `context.Context` initialized at the entry point (`main.go`). This context must respond to OS interrupt signals (SIGINT, SIGTERM) to ensure all I/O-heavy operations can be cancelled cleanly by the user.
|
|
48
|
-
|
|
49
|
-
8. **Parallel Execution & Aggregation:** Systems that execute multiple independent external commands (e.g., Hooks, Lints, Tests) MUST do so in parallel using `sync.WaitGroup` and goroutines. The results (Stdout, Stderr, ExitCode) MUST be aggregated into a standard `core.HookResult` struct and returned together after all operations complete. If any command fails, a specialized error (e.g., `core.HookError`) containing all results MUST be returned to the caller.
|
|
50
|
-
|
|
51
|
-
10. **Complexity Reduction Pattern:** Systems with high cognitive complexity or long methods MUST be refactored using private helper extraction or sub-component isolation to ensure maintainability and testability.
|
|
52
|
-
|
|
53
|
-
## Repository Topology
|
|
54
|
-
- **Topology:** Single-repo (CLI Monolith)
|
|
55
|
-
- **Rationale:** Simplifies distribution as a single binary and reduces dependency management overhead.
|
|
56
|
-
|
|
57
|
-
## Directory Structure
|
|
58
|
-
```
|
|
59
|
-
specforce/
|
|
60
|
-
├── .specforce/
|
|
61
|
-
│ ├── docs/ # Constitution artifacts
|
|
62
|
-
│ ├── specs/ # Feature specifications
|
|
63
|
-
│ ├── templates/ # Specification templates
|
|
64
|
-
│ └── archive/ # Archived specs
|
|
65
|
-
├── src/
|
|
66
|
-
│ ├── cmd/ # CLI entry points
|
|
67
|
-
│ └── internal/ # Core project logic
|
|
68
|
-
│ ├── agent/ # Kit/Agent management
|
|
69
|
-
│ ├── cli/ # CLI command routing
|
|
70
|
-
│ ├── core/ # Shared interfaces (UI)
|
|
71
|
-
│ ├── project/ # Project lifecycle (Init/Bootstrap)
|
|
72
|
-
│ └── tui/ # TUI components and views
|
|
73
|
-
└── Makefile
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
## Directory & Naming Standards
|
|
77
|
-
- **Feature specs:** `.specforce/specs/{slug}/`
|
|
78
|
-
- **Constitution docs:** `.specforce/docs/`
|
|
79
|
-
- **AI Agent Hidden Directories:** Native hidden names MUST be used (e.g., `.claude/`, `.opencode/`, `.kilocode/`, `.agent/`). Root-level agent files (e.g., `CLAUDE.md`) are forbidden.
|
|
80
|
-
- **AI Agent Command Naming:** For specialized agents (OpenCode, KiloCode, Kimi Code), commands MUST be adapted for native discovery:
|
|
81
|
-
- **OpenCode/KiloCode:** Use a flat structure (`commands/`) and follow the `spf.{command}.md` naming convention (e.g., `spf.archive.md`).
|
|
82
|
-
- **Kimi Code:** Use a nested subdirectory structure (`skills/spf-{command}/SKILL.md`) to satisfy the "Skills-First" architecture requirements.
|
|
83
|
-
- **Source layout:** CamelCase for Go packages and filenames within `src/internal/`.
|
|
84
|
-
|
|
85
|
-
## Domain & Identity Standards
|
|
86
|
-
1. **Slug Uniqueness (Identity):** All specification slugs MUST be globally unique within the project's entire lifecycle (including active and archived states).
|
|
87
|
-
2. **Kebab-Case Enforcement:** All slugs MUST be formatted in `kebab-case` to ensure cross-platform compatibility and URL safety.
|
|
88
|
-
3. **Identity Check (Safety):** The system MUST verify slug uniqueness against both `.specforce/specs/` and `.specforce/archive/` before initializing any new feature.
|
|
89
|
-
|
|
90
|
-
## Error Handling Strategy
|
|
91
|
-
- **Domain Error Registry:** `src/internal/core/errors.go` is the single source of truth for all cross-domain sentinel errors (`ErrProjectAlreadyInitialized`, `ErrAgentNotFound`, `ErrInvalidSpecFile`, `ErrInstallerPermissionDenied`). New domains MUST register their errors here.
|
|
92
|
-
- **Layered Error Propagation:** Errors flow upward through layers - I/O → Service → CLI - each layer adding context via `%w` wrapping. The CLI layer is the only layer responsible for translating domain errors into user-facing messages.
|
|
93
|
-
- **`errors.Is` as the Contract:** All cross-layer error checks MUST use `errors.Is` (never string matching). This ensures the chain remains navigable regardless of wrapping depth.
|
|
94
|
-
|
|
95
|
-
## Observability Baseline
|
|
96
|
-
- **Structured Logs:** Minimal logging via CLI output; TUI-driven state reporting.
|
|
97
|
-
- **Error Traceability:** Critical errors must be clearly displayed in the TUI or terminal stderr with context.
|
|
98
|
-
- **Spec Correlation:** Implementation tasks should reference their respective Spec IDs.
|