@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.
Files changed (151) hide show
  1. package/index.js +0 -0
  2. package/package.json +12 -28
  3. package/.geminiignore +0 -15
  4. package/.github/workflows/ci.yml +0 -101
  5. package/.github/workflows/release.yml +0 -51
  6. package/.golangci.yml +0 -17
  7. package/.goreleaser.yaml +0 -39
  8. package/.rgignore +0 -13
  9. package/.specforce/config.yaml +0 -32
  10. package/.specforce/docs/.gitkeep +0 -0
  11. package/.specforce/docs/architecture.md +0 -98
  12. package/.specforce/docs/engineering.md +0 -80
  13. package/.specforce/docs/governance.md +0 -30
  14. package/.specforce/docs/memorial.md +0 -44
  15. package/.specforce/docs/principles.md +0 -31
  16. package/.specforce/docs/security.md +0 -31
  17. package/.specforce/docs/ui-ux.md +0 -129
  18. package/.specforce/specs/.gitkeep +0 -0
  19. package/AGENTS.md +0 -36
  20. package/CONTRIBUTING.md +0 -81
  21. package/Makefile +0 -49
  22. package/assets/logo-header.png +0 -0
  23. package/assets/logo.png +0 -0
  24. package/docs/artifacts.md +0 -41
  25. package/docs/cli.md +0 -73
  26. package/docs/configuration.md +0 -50
  27. package/docs/getting-started.md +0 -110
  28. package/docs/supported-tools.md +0 -14
  29. package/go.mod +0 -35
  30. package/go.sum +0 -61
  31. package/src/cmd/specforce/main.go +0 -23
  32. package/src/cmd/specforce/main_test.go +0 -7
  33. package/src/internal/agent/artifacts/constitution/architecture.yaml +0 -70
  34. package/src/internal/agent/artifacts/constitution/engineering.yaml +0 -52
  35. package/src/internal/agent/artifacts/constitution/governance.yaml +0 -41
  36. package/src/internal/agent/artifacts/constitution/memorial.yaml +0 -55
  37. package/src/internal/agent/artifacts/constitution/principles.yaml +0 -54
  38. package/src/internal/agent/artifacts/constitution/security.yaml +0 -47
  39. package/src/internal/agent/artifacts/constitution/ui-ux.yaml +0 -158
  40. package/src/internal/agent/artifacts/spec/design.yaml +0 -50
  41. package/src/internal/agent/artifacts/spec/requirements.yaml +0 -48
  42. package/src/internal/agent/artifacts/spec/tasks.yaml +0 -55
  43. package/src/internal/agent/compatibility_test.go +0 -120
  44. package/src/internal/agent/cwd_test.go +0 -9
  45. package/src/internal/agent/embed.go +0 -19
  46. package/src/internal/agent/integration_test.go +0 -138
  47. package/src/internal/agent/kit/agents/product-analyst.yaml +0 -31
  48. package/src/internal/agent/kit/agents/technical-developer.yaml +0 -28
  49. package/src/internal/agent/kit/agents/technical-project-planner.yaml +0 -30
  50. package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +0 -36
  51. package/src/internal/agent/kit/agents/technical-solution-architect.yaml +0 -32
  52. package/src/internal/agent/kit/commands/archive.yaml +0 -25
  53. package/src/internal/agent/kit/commands/constitution.yaml +0 -132
  54. package/src/internal/agent/kit/commands/implement.yaml +0 -96
  55. package/src/internal/agent/kit/commands/spec.yaml +0 -94
  56. package/src/internal/agent/kit/instructions/archive.md +0 -68
  57. package/src/internal/agent/kit/kit.yaml +0 -111
  58. package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +0 -56
  59. package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +0 -58
  60. package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +0 -38
  61. package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +0 -52
  62. package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +0 -137
  63. package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +0 -103
  64. package/src/internal/agent/kit_manifests_test.go +0 -58
  65. package/src/internal/agent/manifest.go +0 -15
  66. package/src/internal/agent/registry.go +0 -69
  67. package/src/internal/agent/registry_test.go +0 -51
  68. package/src/internal/agent/translator.go +0 -334
  69. package/src/internal/agent/translator_test.go +0 -734
  70. package/src/internal/cli/archive.go +0 -91
  71. package/src/internal/cli/archive_test.go +0 -67
  72. package/src/internal/cli/cli.go +0 -259
  73. package/src/internal/cli/cli_test.go +0 -130
  74. package/src/internal/cli/cobra/archive.go +0 -26
  75. package/src/internal/cli/cobra/console.go +0 -21
  76. package/src/internal/cli/cobra/constitution.go +0 -44
  77. package/src/internal/cli/cobra/dummy_test.go +0 -7
  78. package/src/internal/cli/cobra/implementation.go +0 -50
  79. package/src/internal/cli/cobra/init.go +0 -23
  80. package/src/internal/cli/cobra/install.go +0 -21
  81. package/src/internal/cli/cobra/root.go +0 -47
  82. package/src/internal/cli/cobra/spec.go +0 -91
  83. package/src/internal/cli/console.go +0 -48
  84. package/src/internal/cli/constitution.go +0 -190
  85. package/src/internal/cli/constitution_test.go +0 -50
  86. package/src/internal/cli/implementation.go +0 -153
  87. package/src/internal/cli/implementation_test.go +0 -165
  88. package/src/internal/cli/spec.go +0 -369
  89. package/src/internal/cli/spec_test.go +0 -85
  90. package/src/internal/constitution/registry.go +0 -139
  91. package/src/internal/constitution/registry_test.go +0 -97
  92. package/src/internal/constitution/status.go +0 -70
  93. package/src/internal/constitution/status_test.go +0 -160
  94. package/src/internal/core/blueprint.go +0 -49
  95. package/src/internal/core/blueprint_test.go +0 -58
  96. package/src/internal/core/config.go +0 -124
  97. package/src/internal/core/config_test.go +0 -145
  98. package/src/internal/core/constants.go +0 -13
  99. package/src/internal/core/errors.go +0 -31
  100. package/src/internal/core/errors_test.go +0 -48
  101. package/src/internal/core/hooks.go +0 -89
  102. package/src/internal/core/hooks_test.go +0 -51
  103. package/src/internal/core/kit.go +0 -15
  104. package/src/internal/core/kit_test.go +0 -65
  105. package/src/internal/core/path.go +0 -115
  106. package/src/internal/core/path_test.go +0 -101
  107. package/src/internal/core/ui.go +0 -19
  108. package/src/internal/installer/dependencies.go +0 -23
  109. package/src/internal/installer/install.go +0 -89
  110. package/src/internal/installer/installer.go +0 -45
  111. package/src/internal/installer/installer_test.go +0 -96
  112. package/src/internal/project/agents_md.go +0 -108
  113. package/src/internal/project/agents_md_test.go +0 -101
  114. package/src/internal/project/bootstrapper.go +0 -64
  115. package/src/internal/project/bootstrapper_test.go +0 -89
  116. package/src/internal/project/detector.go +0 -35
  117. package/src/internal/project/detector_test.go +0 -96
  118. package/src/internal/project/refresh_integration_test.go +0 -86
  119. package/src/internal/project/service.go +0 -93
  120. package/src/internal/project/service_test.go +0 -135
  121. package/src/internal/spec/archive.go +0 -49
  122. package/src/internal/spec/archive_test.go +0 -55
  123. package/src/internal/spec/discovery.go +0 -53
  124. package/src/internal/spec/discovery_test.go +0 -60
  125. package/src/internal/spec/implementation.go +0 -296
  126. package/src/internal/spec/implementation_test.go +0 -253
  127. package/src/internal/spec/registry.go +0 -142
  128. package/src/internal/spec/registry_test.go +0 -105
  129. package/src/internal/spec/scanner.go +0 -219
  130. package/src/internal/spec/scanner_test.go +0 -243
  131. package/src/internal/spec/service.go +0 -157
  132. package/src/internal/spec/service_test.go +0 -238
  133. package/src/internal/spec/status.go +0 -94
  134. package/src/internal/spec/status_test.go +0 -146
  135. package/src/internal/spec/tasks.go +0 -103
  136. package/src/internal/spec/tasks_test.go +0 -137
  137. package/src/internal/tui/components.go +0 -132
  138. package/src/internal/tui/console.go +0 -247
  139. package/src/internal/tui/console_test.go +0 -19
  140. package/src/internal/tui/constitution.go +0 -36
  141. package/src/internal/tui/constitution_test.go +0 -32
  142. package/src/internal/tui/implementation.go +0 -151
  143. package/src/internal/tui/logo.go +0 -89
  144. package/src/internal/tui/multiselect.go +0 -199
  145. package/src/internal/tui/progressbar.go +0 -37
  146. package/src/internal/tui/progressbar_test.go +0 -30
  147. package/src/internal/tui/spec.go +0 -35
  148. package/src/internal/tui/spinner.go +0 -66
  149. package/src/internal/tui/terminal.go +0 -18
  150. package/src/internal/tui/theme.go +0 -125
  151. 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",
4
- "description": "SpecForce Kit CLI - Distributed via GoReleaser",
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": "bin/specforce"
10
+ "specforce": "index.js"
11
11
  },
12
- "scripts": {
13
- "postinstall": "go-npm install",
14
- "uninstall": "go-npm uninstall"
15
- },
16
- "dependencies": {
17
- "go-npm": "^0.1.1"
18
- },
19
- "goBinary": {
20
- "name": "specforce",
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
@@ -1,15 +0,0 @@
1
- # --- Padrões Globais ---
2
- .git/
3
- .gitignore
4
- .env.local
5
- .env.*.local
6
- *.log
7
- dist/
8
- vendor/
9
- node_modules/
10
-
11
- # --- Arquivos de Sistema e IDE ---
12
- .idea/
13
- .vscode/
14
- .DS_Store
15
- Thumbs.db
@@ -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
@@ -1,17 +0,0 @@
1
- # Arquivo: .golangci.yml
2
-
3
- linters:
4
- enable:
5
- - gocyclo
6
- - gocognit
7
- - funlen
8
- - dupl
9
-
10
- linters-settings:
11
- gocyclo:
12
- min-complexity: 35
13
- gocognit:
14
- min-complexity: 35
15
- funlen:
16
- lines: 120
17
- 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,13 +0,0 @@
1
- node_modules/
2
- vendor/
3
- var/*
4
- !var/log/
5
- !var/log/**
6
- dist/
7
- build/
8
- coverage/
9
- .next/
10
- public/build/
11
- .agent/.gemini/
12
- .agent/.claude/
13
- .specforce/archive/
@@ -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 ./..."
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.