@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.
- package/index.js +0 -0
- package/package.json +12 -28
- package/.geminiignore +0 -15
- package/.github/workflows/ci.yml +0 -101
- package/.github/workflows/release.yml +0 -51
- package/.golangci.yml +0 -17
- package/.goreleaser.yaml +0 -39
- package/.rgignore +0 -13
- 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 -80
- package/.specforce/docs/governance.md +0 -30
- package/.specforce/docs/memorial.md +0 -44
- 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 -36
- 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 -50
- package/docs/getting-started.md +0 -110
- package/docs/supported-tools.md +0 -14
- 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 -108
- package/src/internal/project/agents_md_test.go +0 -101
- 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
|
File without changes
|
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.6",
|
|
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.6",
|
|
17
|
+
"@jeancodogno/specforce-kit-linux-arm64": "0.1.6",
|
|
18
|
+
"@jeancodogno/specforce-kit-darwin-x64": "0.1.6",
|
|
19
|
+
"@jeancodogno/specforce-kit-darwin-arm64": "0.1.6",
|
|
20
|
+
"@jeancodogno/specforce-kit-win32-x64": "0.1.6"
|
|
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,101 +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@v6
|
|
29
|
-
with:
|
|
30
|
-
version: latest
|
|
31
|
-
args: --timeout=5m
|
|
32
|
-
install-mode: goinstall
|
|
33
|
-
|
|
34
|
-
security:
|
|
35
|
-
name: Security
|
|
36
|
-
runs-on: ubuntu-latest
|
|
37
|
-
steps:
|
|
38
|
-
- name: Checkout code
|
|
39
|
-
uses: actions/checkout@v4
|
|
40
|
-
|
|
41
|
-
- name: Setup Go
|
|
42
|
-
uses: actions/setup-go@v5
|
|
43
|
-
with:
|
|
44
|
-
go-version: "1.26.2"
|
|
45
|
-
cache: true
|
|
46
|
-
|
|
47
|
-
- name: Bootstrap Tools
|
|
48
|
-
run: make bootstrap
|
|
49
|
-
|
|
50
|
-
- name: Run Security Scans
|
|
51
|
-
run: make security
|
|
52
|
-
continue-on-error: true # Upload SARIF even if findings exist
|
|
53
|
-
|
|
54
|
-
- name: Upload SARIF
|
|
55
|
-
uses: github/codeql-action/upload-sarif@v3
|
|
56
|
-
with:
|
|
57
|
-
sarif_file: results.sarif
|
|
58
|
-
|
|
59
|
-
test:
|
|
60
|
-
name: Unit Tests
|
|
61
|
-
runs-on: ubuntu-latest
|
|
62
|
-
steps:
|
|
63
|
-
- name: Checkout code
|
|
64
|
-
uses: actions/checkout@v4
|
|
65
|
-
|
|
66
|
-
- name: Setup Go
|
|
67
|
-
uses: actions/setup-go@v5
|
|
68
|
-
with:
|
|
69
|
-
go-version: "1.26.2"
|
|
70
|
-
cache: true
|
|
71
|
-
|
|
72
|
-
- name: Run Tests
|
|
73
|
-
run: make test-coverage
|
|
74
|
-
|
|
75
|
-
- name: Check Coverage
|
|
76
|
-
run: |
|
|
77
|
-
CORE_COVERAGE=$(go tool cover -func=coverage.out | grep -E "src/internal/(core|project|spec)" | awk '{count++; sum+=$3} END {print sum/count}' | tr ',' '.')
|
|
78
|
-
echo "Core Packages Average Coverage: $CORE_COVERAGE%"
|
|
79
|
-
if (( $(echo "$CORE_COVERAGE < 80" | bc -l) )); then
|
|
80
|
-
echo "Core coverage is below 80%"
|
|
81
|
-
exit 1
|
|
82
|
-
fi
|
|
83
|
-
|
|
84
|
-
quality:
|
|
85
|
-
name: Mutation Quality
|
|
86
|
-
runs-on: ubuntu-latest
|
|
87
|
-
steps:
|
|
88
|
-
- name: Checkout code
|
|
89
|
-
uses: actions/checkout@v4
|
|
90
|
-
|
|
91
|
-
- name: Setup Go
|
|
92
|
-
uses: actions/setup-go@v5
|
|
93
|
-
with:
|
|
94
|
-
go-version: "1.26.2"
|
|
95
|
-
cache: true
|
|
96
|
-
|
|
97
|
-
- name: Bootstrap Tools
|
|
98
|
-
run: make bootstrap
|
|
99
|
-
|
|
100
|
-
- name: Run Mutation Tests
|
|
101
|
-
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
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
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.
|
|
@@ -1,80 +0,0 @@
|
|
|
1
|
-
# Engineering
|
|
2
|
-
|
|
3
|
-
## Coding Standards
|
|
4
|
-
- **Backend Style & Linters:** Go 1.24+ following standard `gofmt` and `golangci-lint` (Level 8 equivalent).
|
|
5
|
-
- **CLI Standard:** All new commands MUST be implemented using the Cobra framework (nested under `src/internal/cli/cobra`).
|
|
6
|
-
- **Frontend Style & Linters:** Bubbletea/Lipgloss for TUI consistency; styles encapsulated in a shared `tui` package.
|
|
7
|
-
- **Typing Strictness:** Rigid Go typing. Minimize use of `interface{}` or `any`; prefer explicit types and interfaces for testing mocks.
|
|
8
|
-
- **Embedded Registry Pattern:** Components discovered via metadata MUST be managed by a centralized `Registry` type. This registry should be initialized once (usually with an `fs.FS`) and passed as a dependency to other services or UI components.
|
|
9
|
-
- **Agent-Specific Artifact Mapping:** To support diverse AI coding agents with differing directory conventions, the framework MUST use centralized `kit.yaml` (kit-level) and `mapping.yaml` (legacy/blueprint-level) files. These files translate internal Specforce artifact paths to the native hidden directory names of each supported agent (e.g., `.kimi/`, `.claude/`).
|
|
10
|
-
- **Generic Wildcard Expansion:** Mapping configurations in `kit.yaml` MUST support the `*` wildcard in both `path` and `name` fields. The system MUST replace the `*` with the artifact's slug (source filename without extension).
|
|
11
|
-
- **Strict Category Whitelisting:** Artifacts are only installed for an agent if their source category (e.g., `agents`, `commands`, `skills`) is explicitly defined in that agent's `mappings` within `kit.yaml`. Categories not present in the mapping MUST be ignored by default.
|
|
12
|
-
- **Slug Defaulting:** If a mapping's `name` field is empty, the system MUST default to the artifact's slug.
|
|
13
|
-
- **Hierarchy Preservation:** For static mappings (no `*` in path), the system MUST preserve any sub-directory hierarchy found in the source category.
|
|
14
|
-
- **Agent Tool Addition Process:** To integrate a new agent tool into the Specforce ecosystem, developers MUST follow these steps:
|
|
15
|
-
1. **Register Constant:** Add the tool's hidden directory name (e.g., `.newagent/`) to the `ToolPrefixes` slice in `src/internal/core/constants.go`.
|
|
16
|
-
2. **Define Mapping:** Update `src/internal/agent/kit/kit.yaml` with the tool's `name`, `description`, `target` directory, and `mappings` for required categories (e.g., `commands`, `skills`).
|
|
17
|
-
3. **Granular Pathing:** Utilize the mapping-level `target` override and environment variable expansion (e.g., `${VAR:-DEFAULT}`) to support global path requirements when necessary.
|
|
18
|
-
4. **Enable Global Writing (Optional):** If the agent requires global system access (outside the project root), add its slug to the `globalEnabledAgents` allow-list in `src/internal/agent/translator.go`.
|
|
19
|
-
- **Agent Command Flatness:** For OpenCode and KiloCode, commands MUST be stored directly in a flat `commands/` subfolder using the `spf.*` prefix to ensure correct discovery by those agents.
|
|
20
|
-
- **Generated Markdown Files:** Any automatically generated documentation files (e.g., `AGENTS.md`) MUST use explicit start and end markers (e.g., `<!-- SPECFORCE_AGENTS_START -->` and `<!-- SPECFORCE_AGENTS_END -->`) to delimit the framework-managed content. The update logic MUST preserve any user-written content located outside these markers.
|
|
21
|
-
- **Service Layer Pattern:** Domain services MUST be initialized with their dependencies (filesystems, registries, etc.) and expose UI-agnostic methods. They MUST depend on the `core.UI` interface for reporting progress and logging, ensuring they remain decoupled from specific frontend implementations.
|
|
22
|
-
- **Instruction Injection Pattern:** Services responsible for generating or displaying agent-facing content (e.g., Spec artifacts, Implementation reports) MUST merge global instructions from `core.ProjectConfig` into their output. This ensures that the orchestration loop respects project-specific constraints without modifying the core Specforce protocol.
|
|
23
|
-
- **Hook-Based Verification Gating:** Critical state transitions (e.g., marking a task as `FINISHED`) MUST be gated by project-defined external hooks. If a hook fails (non-zero exit code), the transition MUST be blocked, the original state MUST NOT be modified, and the CLI command MUST exit with a non-zero status code to support shell command chaining.
|
|
24
|
-
- **Interactive Confirmation Gating:** Irreversible or high-impact operations (e.g., overwriting existing tool instructions or deleting specs) MUST be gated by an explicit `Confirm` prompt via the `core.UI` interface. The system MUST NOT proceed without affirmative user consent (Sim/Yes).
|
|
25
|
-
- **DTO Pattern (Data Transfer Objects):** Services SHOULD use explicit structs (DTOs) for complex input configurations or output reports. This maintains a stable contract between the CLI/TUI layer and the domain logic.
|
|
26
|
-
- **Complexity Limits:** Maximum function length: 50 lines. Maximum cyclomatic complexity: 10 per function.
|
|
27
|
-
- **Refactoring Patterns:**
|
|
28
|
-
- **Surgical Helper Extraction:** When a function exceeds complexity or length limits, extract logic into private helper functions within the same file to maintain readability without changing the public contract.
|
|
29
|
-
- **Explicit Error Ignoring (Tests):** In test files, if an error from a function like `os.RemoveAll` or `os.Chdir` is safe to ignore, use `_ =` to make the omission explicit and satisfy linting requirements.
|
|
30
|
-
- **Permission Hardening:** All I/O operations MUST use the most restrictive permissions possible:
|
|
31
|
-
- **Directories:** Use `0750` for all directory creation (`os.MkdirAll`).
|
|
32
|
-
- **Files:** Use `0600` for all sensitive or system-internal files (e.g., config, tasks, implementation reports). Use `0644` only where public read access by external tools is strictly required.
|
|
33
|
-
|
|
34
|
-
- **Instruction-Driven Agent Pattern:** Agent command definitions (`.yaml`) SHOULD NOT contain complex, hardcoded logic or multi-step instructions. Instead, they MUST trigger a dedicated Specforce CLI command (e.g., `specforce archive instructions`) to retrieve a dynamic instruction set. This allows the framework to inject global context (Constitution), core kit rules, and project-specific overrides from `config.yaml` without updating the agent's definition.
|
|
35
|
-
- **Knowledge-First Archival:** The feature archival process MUST include a "Knowledge Harvesting" phase. Before a specification is archived, the agent or developer MUST update the project's `.specforce/docs/memorial.md` with lessons learned, established precedents, and critical architectural decisions discovered during the implementation.
|
|
36
|
-
|
|
37
|
-
## Agent Orchestration Protocol
|
|
38
|
-
1. **Mandatory Discovery:** Agents MUST call `specforce spec list` and `specforce constitution status --json` before initializing a new specification to ensure they have the full project context.
|
|
39
|
-
2. **Interrogation over Hallucination:** Agents MUST NOT guess user intent. They must use interrogation tools to ask clarifying questions until a clear feature idea is reached.
|
|
40
|
-
3. **Primary Orchestration Only:** Agents MUST remain in their primary orchestration loop and NOT use specialized "plan" or "design" modes for requirement discovery.
|
|
41
|
-
4. **Mandatory Skill Header Injection:** For agents using "Skills" (e.g., Kimi Code), all generated `SKILL.md` files (from skills or commands) MUST include a YAML frontmatter header with `name` and `description` to ensure native discovery.
|
|
42
|
-
5. **Binary-Path Standard:** All agent-triggered CLI commands MUST use the global binary `specforce` (not `./specforce`) to ensure cross-platform consistency.
|
|
43
|
-
|
|
44
|
-
## Context Handling
|
|
45
|
-
- **Mandatory Propagation:** All functions performing I/O, recursion, or loops MUST accept `context.Context` as their first argument.
|
|
46
|
-
- **Strict Separation:** `context.Context` MUST NOT be stored in a struct. It must be passed explicitly through the call stack to maintain visibility of the operation's lifecycle.
|
|
47
|
-
- *Exception:* UI models (e.g., Bubbletea models) may store a context for managing background "tick" or "refresh" operations, provided it is derived from the root lifecycle.
|
|
48
|
-
- **Cancellation Checks:** Any function that iterates over a collection or performs recursive calls MUST check for context cancellation (e.g., `if err := ctx.Err(); err != nil { return err }`) at the start of each iteration or recursion level.
|
|
49
|
-
|
|
50
|
-
## Testing Strategy
|
|
51
|
-
- **Frameworks:** Standard Go `testing` package; optional use of `stretchr/testify` for assertions.
|
|
52
|
-
- **Coverage Gate:** 80% minimum coverage for core domain packages (`src/internal/core`, `src/internal/project`, `src/internal/spec`).
|
|
53
|
-
- **Mutation Testing:** Projects SHOULD use `Gremlins` for mutation testing to verify test suite efficacy. Core packages MUST target a mutation score > 0 (all survivors investigated).
|
|
54
|
-
- **Unit Testing Rules:** All core logic and state transitions MUST have automated unit tests.
|
|
55
|
-
- **Regression Rules:** Any reported bug MUST be reproduced with a failing test case before being fixed.
|
|
56
|
-
|
|
57
|
-
## Delivery Standards & DoD
|
|
58
|
-
- **Commit Standard:** Conventional Commits (e.g., `feat:`, `fix:`, `docs:`, `chore:`).
|
|
59
|
-
- **Continuous Integration:** PRs MUST trigger a multi-job parallel pipeline (Lint, Security, Test, Quality) for rapid feedback.
|
|
60
|
-
- **Security Scans:** Security checks MUST use `gosec` and `govulncheck`. Findings MUST be reported via SARIF to the GitHub Security tab.
|
|
61
|
-
- **Definition of Done (DoD):**
|
|
62
|
-
- [ ] Code passes `golangci-lint` and `go test`.
|
|
63
|
-
- [ ] Coverage gate is met or maintained.
|
|
64
|
-
- [ ] Security scans pass (zero critical findings).
|
|
65
|
-
- [ ] TUI views are manually verified for layout consistency.
|
|
66
|
-
- [ ] Feature Specification status is updated to "Implemented".
|
|
67
|
-
- [ ] The Memorial is updated with relevant "Last Actions".
|
|
68
|
-
|
|
69
|
-
## Error Handling Standards
|
|
70
|
-
- **Sentinel Errors:** All domain-specific errors MUST be defined as package-level sentinel variables using `errors.New()` in `src/internal/core/errors.go`. No ad-hoc error strings in business logic.
|
|
71
|
-
- **Error Wrapping:** All I/O and service-boundary errors MUST be wrapped with context using `fmt.Errorf("failed to <operation>: %w", err)`. Never return raw OS/library errors.
|
|
72
|
-
- **Domain + OS Wrapping:** When combining a sentinel domain error with an originating OS error, use `errors.Join`: `fmt.Errorf("context: %w", errors.Join(core.ErrXxx, osErr))`. This preserves both for `errors.Is` inspection.
|
|
73
|
-
- **CLI Handler Pattern:** Command handlers in `src/internal/cli/cli.go` MUST use an `errors.Is` switch to intercept known domain errors, emit a user-friendly message via `core.UI`, and return `nil` - preventing cobra from printing raw error strings to the user.
|
|
74
|
-
- **Idempotency Guards:** Operations that mutate persistent state (e.g., `BootstrapProject`) MUST guard against re-execution by checking existing state and returning the appropriate domain sentinel error if the operation would be redundant.
|
|
75
|
-
|
|
76
|
-
## Specification & Task Organization
|
|
77
|
-
- **Hierarchical Task Structure:** Implementation roadmaps (`tasks.md`) MUST use a hierarchical structure to group atomic tasks.
|
|
78
|
-
- **Phases (H3):** Use `### Phase {N}: {Title}` for logical groupings.
|
|
79
|
-
- **Tasks (H4):** Use `#### T{Phase}.{Task}: {Title}` for individual implementation steps.
|
|
80
|
-
- **DTO Pattern for Flat Access:** Domain models that implement nested structures (like `ImplementationReport` with `Phases`) MUST provide a `Tasks()` helper method that returns a flattened slice of all tasks. This ensures backward compatibility for scanners and progress calculators that expect a sequential list.
|
|
@@ -1,30 +0,0 @@
|
|
|
1
|
-
# Governance
|
|
2
|
-
|
|
3
|
-
## Versioning Policy (SemVer)
|
|
4
|
-
- **MAJOR:** Breaking constitutional or architectural process change. Requires team consensus.
|
|
5
|
-
- **MINOR:** New principle or standard added without breaking prior commitments.
|
|
6
|
-
- **PATCH:** Clarifications, typo fixes, wording, and non-functional adjustments.
|
|
7
|
-
|
|
8
|
-
## Amendment Process
|
|
9
|
-
1. Propose the change with a clear rationale and impact analysis.
|
|
10
|
-
2. Classify the SemVer impact (Major/Minor/Patch).
|
|
11
|
-
3. Update all affected docs in `.specforce/docs/`.
|
|
12
|
-
4. Record the version bump and the amendment date in the document's header.
|
|
13
|
-
|
|
14
|
-
## Ownership & Review
|
|
15
|
-
- **Owner:** Project Lead / Solutions Architect.
|
|
16
|
-
- **Review Cadence:** Quarterly or after every Major release.
|
|
17
|
-
|
|
18
|
-
## Agentic Authority & Boundaries
|
|
19
|
-
- **Permitted AI Autonomous Actions:**
|
|
20
|
-
- Propose new Spec drafts for requested features.
|
|
21
|
-
- Generate implementation code based on approved Specs.
|
|
22
|
-
- Update the Project Memorial (`.specforce/docs/memorial.md`) with lessons learned and architectural precedents during archival or implementation.
|
|
23
|
-
- Refactor existing code within the scope of a feature.
|
|
24
|
-
- **Prohibited AI Actions (Requires Human Approval):**
|
|
25
|
-
- Modify the project Constitution (`.specforce/docs/`).
|
|
26
|
-
- Approve Specs for implementation.
|
|
27
|
-
- Change project-wide architectural patterns or technology stack.
|
|
28
|
-
- Approve Pull Requests or perform final merges.
|
|
29
|
-
- **Conflict Resolution Protocol:**
|
|
30
|
-
- If a user prompt or a draft Spec contradicts the Constitution, the AI MUST refuse the prompt and cite the violated Principle/Rule.
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
# Memorial (Active Memory)
|
|
2
|
-
|
|
3
|
-
> **FOR AI AGENTS: RULES OF ENGAGEMENT**
|
|
4
|
-
> This is your cross-session memory file. You MUST obey these rules:
|
|
5
|
-
> 1. **READ THIS FIRST** before starting any task, debugging, or writing code in this repository.
|
|
6
|
-
> 2. **TRIAGE:** Read `Critical Now` first, then `Last Actions`. Only read lessons if they match your current scope.
|
|
7
|
-
> 3. **STRICT LIMITS (DO NOT BLOAT):**
|
|
8
|
-
> - Max 3 `Critical Now` bullets.
|
|
9
|
-
> - Max 5 `Last Actions` entries.
|
|
10
|
-
> - Max 7 `Active Lessons`.
|
|
11
|
-
> - Max 5 `Pending Decisions`.
|
|
12
|
-
> 4. **GARBAGE COLLECTION:** If a list is full, you MUST delete the oldest/least relevant item before adding a new one.
|
|
13
|
-
> 5. **DISTILLATION:** If a lesson or decision becomes a permanent rule, you MUST move it to the official Constitution files (`engineering.md`, `architecture.md`, etc.) and completely delete it from here.
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## Critical Now
|
|
18
|
-
- [2026-04-19] [Tasks] Hierarchical task organization (Phases H3 / Tasks H4) implemented. Agents should now use this for all new feature roadmaps.
|
|
19
|
-
|
|
20
|
-
## Last Actions
|
|
21
|
-
- **Date:** 2026-04-25
|
|
22
|
-
- **Scope:** Agent / CLI
|
|
23
|
-
- **Completed:** Implemented `specforce archive instructions` command and Instruction-Driven Agent Pattern for feature archival.
|
|
24
|
-
- **Next:** Apply the Instruction-Driven pattern to other agent commands (e.g., implement, spec).
|
|
25
|
-
- **Relevant Files:** src/internal/cli/archive.go, src/internal/agent/kit/instructions/archive.md, src/internal/agent/kit/commands/archive.yaml
|
|
26
|
-
|
|
27
|
-
## Active Lessons & Anti-Patterns
|
|
28
|
-
- **First Seen:**
|
|
29
|
-
- **Last Seen:**
|
|
30
|
-
- **Scope:**
|
|
31
|
-
- **Symptom:**
|
|
32
|
-
- **Avoid:**
|
|
33
|
-
- **Do Instead:**
|
|
34
|
-
- **Recurrence Count:**
|
|
35
|
-
- **Status:**
|
|
36
|
-
- **Distill To:**
|
|
37
|
-
|
|
38
|
-
## Pending Decisions (Need Distillation)
|
|
39
|
-
- **Date:**
|
|
40
|
-
- **Scope:**
|
|
41
|
-
- **Decision:**
|
|
42
|
-
- **Why:**
|
|
43
|
-
- **Validate By:**
|
|
44
|
-
- **Distill To:**
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
# Principles
|
|
2
|
-
|
|
3
|
-
## Mission
|
|
4
|
-
Specforce Kit is a professional-grade framework and repository for Spec-Driven Development (SDD), providing the standard agent configurations, TUI tools, and documentation templates to enable AI-orchestrated engineering. It serves as the "source of truth" for SDD workflows, ensuring that project boundaries, architectural integrity, and multi-agent collaboration are strictly enforced from project initialization to implementation.
|
|
5
|
-
|
|
6
|
-
## User Personas
|
|
7
|
-
- **Persona 1:** Lead Solutions Architect
|
|
8
|
-
- **Role:** Designs the technical foundations and non-negotiable rules for a new project.
|
|
9
|
-
- **Goal:** Standardize the engineering posture and architectural boundaries across multiple AI-driven teams.
|
|
10
|
-
- **Pain Point:** Difficulty in consistently conveying "hard rules" and technical constraints to diverse AI agents.
|
|
11
|
-
- **Persona 2:** AI-First Senior Developer
|
|
12
|
-
- **Role:** Implements complex features and refactors legacy code in an AI-first environment.
|
|
13
|
-
- **Goal:** Leverage AI agents to generate high-quality, spec-compliant code without risking regressions or architectural drift.
|
|
14
|
-
- **Pain Point:** The overhead of manually checking if AI-generated code violates project-wide principles or design patterns.
|
|
15
|
-
|
|
16
|
-
## Golden Rules
|
|
17
|
-
1. **Rule 1:** Specs are Immutable Once Approved. No implementation change is allowed without first updating and re-approving the Spec artifact.
|
|
18
|
-
2. **Rule 2:** Behavioral Correctness Over Feature Speed. Rigorous verification and testing are mandatory; unverified code is considered incomplete.
|
|
19
|
-
3. **Rule 3:** AI-Augmented, Human-Governed. AI agents are executors; all final architectural decisions and Spec approvals must be governed by a human Lead.
|
|
20
|
-
|
|
21
|
-
## Product Boundaries
|
|
22
|
-
|
|
23
|
-
### In Scope
|
|
24
|
-
- Standardization of AI agent "kits" (rules, instructions, and tools).
|
|
25
|
-
- Lifecycle management of project Constitution and feature Specifications.
|
|
26
|
-
- TUI-driven interactive commands for project initialization, status tracking, and console-based management.
|
|
27
|
-
|
|
28
|
-
### Out of Scope (Anti-Goals)
|
|
29
|
-
- Not a replacement for version control systems (Git).
|
|
30
|
-
- Does not aim to automate the entire software development lifecycle; it focuses on the design-to-implementation transition.
|
|
31
|
-
- Avoids project-specific business logic; it provides the framework to manage such logic.
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
# Security Posture
|
|
2
|
-
|
|
3
|
-
## Identity & Access Control
|
|
4
|
-
- **Authentication Strategy:** Local-only execution; relies on underlying OS user identity and file permissions.
|
|
5
|
-
- **Token/Session Lifecycle:** N/A (Stateless CLI).
|
|
6
|
-
- **Authorization Model:** Implicit (The user running the CLI must have RW permissions on the project directory).
|
|
7
|
-
- **Tenant Isolation (IDOR Prevention):** N/A (Single-tenant; project scope is the current directory).
|
|
8
|
-
|
|
9
|
-
## Data Protection & Cryptography
|
|
10
|
-
- **Data in Transit:** N/A (Internal tool; all data flows remain local).
|
|
11
|
-
- **Data at Rest:** Plaintext (The project relies on standard Git-based access control and disk encryption).
|
|
12
|
-
- **Secret Management:** Strictly via environment variables. Sensitive keys (e.g., AI provider API keys) must never be committed or written to disk.
|
|
13
|
-
|
|
14
|
-
## Auditing & Logging
|
|
15
|
-
- **Auditable Events:**
|
|
16
|
-
- Initialization of a new project/agent.
|
|
17
|
-
- Updates to the Constitution artifacts.
|
|
18
|
-
- Approval of feature Specifications.
|
|
19
|
-
- **Log Sanitization & PII:** Redact environment variables and API keys from terminal output or generated logs.
|
|
20
|
-
|
|
21
|
-
## Platform Hardening
|
|
22
|
-
- **Secure Path Resolution:** All file system operations MUST use a centralized secure path resolver. This utility MUST:
|
|
23
|
-
1. Call `filepath.Clean(path)`.
|
|
24
|
-
2. Ensure the resulting path remains within the project's root boundary.
|
|
25
|
-
3. Reject any path that attempts to escape via directory traversal (e.g., `../`).
|
|
26
|
-
- **Command Sanitization:** Subprocess execution (e.g., Hooks) MUST NOT use shell-mediated execution (e.g., `sh -c`). Instead, command strings MUST be parsed into a base command and an explicit slice of arguments to prevent shell injection.
|
|
27
|
-
|
|
28
|
-
## AI Security Constraints
|
|
29
|
-
- The AI MUST NEVER hardcode passwords, tokens, or API keys in the source code. All secrets MUST be mocked via environment variables.
|
|
30
|
-
- The AI MUST ALWAYS use parameterized inputs when interacting with external processes or generating dynamic content. Raw string concatenation for executable logic is strictly forbidden.
|
|
31
|
-
- The AI MUST strictly validate all inputs at the project boundary (CLI arguments, file reads) before processing domain logic.
|