@jeancodogno/specforce-kit 0.1.4 → 0.1.5

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.
@@ -25,11 +25,14 @@ jobs:
25
25
  cache: true
26
26
 
27
27
  - name: golangci-lint
28
- uses: golangci/golangci-lint-action@v6
28
+ uses: golangci/golangci-lint-action@v9
29
29
  with:
30
30
  version: latest
31
+ verify: false
31
32
  args: --timeout=5m
32
33
  install-mode: goinstall
34
+ skip-pkg-cache: true
35
+
33
36
 
34
37
  security:
35
38
  name: Security
package/.golangci.yml CHANGED
@@ -1,4 +1,11 @@
1
1
  # Arquivo: .golangci.yml
2
+ version: 2
3
+
4
+ run:
5
+ concurrency: 4
6
+ timeout: 5m
7
+ issues-exit-code: 1
8
+ tests: true
2
9
 
3
10
  linters:
4
11
  enable:
@@ -0,0 +1,38 @@
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.
@@ -0,0 +1,35 @@
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.
@@ -0,0 +1,76 @@
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.
@@ -7,7 +7,11 @@
7
7
  - **Typing Strictness:** Rigid Go typing. Minimize use of `interface{}` or `any`; prefer explicit types and interfaces for testing mocks.
8
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
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).
10
+ - **Automated Platform Configuration:** The framework MUST automatically set up environment-specific discovery rules for supported agents during project initialization or refresh. This includes:
11
+ - Creating `.gemini/settings.json` with the correct `fileName` context mapping.
12
+ - Creating relative symbolic links (e.g., `.agent/rules/AGENTS.md -> ../../AGENTS.md`) to expose global project rules to agents that use standardized rules directories.
13
+ - Ensuring all symlinks are relative to maintain project portability.
14
+ - **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
15
  - **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
16
  - **Slug Defaulting:** If a mapping's `name` field is empty, the system MUST default to the artifact's slug.
13
17
  - **Hierarchy Preservation:** For static mappings (no `*` in path), the system MUST preserve any sub-directory hierarchy found in the source category.
@@ -16,24 +16,25 @@
16
16
 
17
17
  ## Critical Now
18
18
  - [2026-04-19] [Tasks] Hierarchical task organization (Phases H3 / Tasks H4) implemented. Agents should now use this for all new feature roadmaps.
19
+ - [2026-04-26] [Linter] `.golangci.yml` requires `version: "2"` for compatibility with current `golangci-lint` versions.
19
20
 
20
21
  ## 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
22
+ - **Date:** 2026-04-26
23
+ - **Scope:** Agent / Project Setup
24
+ - **Completed:** Corrected `AGENTS.md` hook names and implemented automated platform-specific configurations (Gemini settings, Antigravity/Claude symlinks).
25
+ - **Next:** Monitor agent discovery performance across different platforms with the new automated links.
26
+ - **Relevant Files:** src/internal/project/agents_md.go, docs/configuration.md, docs/supported-tools.md
26
27
 
27
28
  ## 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:**
29
+ - **First Seen:** 2026-04-26
30
+ - **Last Seen:** 2026-04-26
31
+ - **Scope:** Project Initialization / AI Onboarding
32
+ - **Symptom:** AI agents (Gemini, Claude Code) failing to discover project rules after `specforce init`.
33
+ - **Avoid:** Manual setup instructions for each platform.
34
+ - **Do Instead:** Automated environment-specific configuration (symlinks/settings files) triggered during `EnsureAgentsMD`.
35
+ - **Recurrence Count:** 1
36
+ - **Status:** Resolved
37
+ - **Distill To:** engineering.md
37
38
 
38
39
  ## Pending Decisions (Need Distillation)
39
40
  - **Date:**
package/AGENTS.md CHANGED
@@ -24,13 +24,23 @@ Specforce allows developers to gate state transitions (e.g., finishing a task) u
24
24
  ```yaml
25
25
  # config.yaml example
26
26
  hooks:
27
- on_task_finish:
28
- command: "make lint && make test"
29
- on_spec_finish:
30
- command: "make build"
27
+ on_task_finished:
28
+ - "make lint"
29
+ - "make test"
30
+ on_phase_finished:
31
+ - "go test ./src/internal/..."
32
+ on_all_tasks_finished:
33
+ - "go test ./..."
31
34
  ```
32
35
  If a hook fails, the state transition will be blocked.
33
36
 
34
37
  *Note: The content above is managed by Specforce. Do not edit inside these markers.*
35
38
  <!-- SPECFORCE_AGENTS_END -->
36
39
 
40
+
41
+
42
+
43
+
44
+
45
+
46
+
@@ -33,8 +33,17 @@ hooks:
33
33
  on_task_finished:
34
34
  - "npm run lint"
35
35
  - "npm run test"
36
+ on_phase_finished:
37
+ - "npm run integration-tests"
38
+ on_all_tasks_finished:
39
+ - "npm run e2e-tests"
36
40
  ```
37
41
 
42
+ ### Supported Hooks:
43
+ - **`on_task_finished`**: Triggered after each individual task is completed.
44
+ - **`on_phase_finished`**: Triggered after all tasks in a specific Phase (H3) are completed.
45
+ - **`on_all_tasks_finished`**: Triggered after the entire implementation roadmap is completed.
46
+
38
47
  ### How does it work?
39
48
  1. The agent attempts to mark a task from its specification as finished.
40
49
  2. Specforce pauses the agent and executes `npm run lint` and `npm run test`.
@@ -11,4 +11,18 @@ Specforce is designed to be independent of any specific tool or ecosystem (tool-
11
11
  - **Codex**
12
12
  - **Antigravity**
13
13
 
14
+ ## Automated Configuration
15
+
16
+ Specforce automatically configures your environment to ensure agents can discover the project rules defined in `AGENTS.md`. When running `specforce init` or updating tools:
17
+
18
+ - **Gemini CLI**: Automatically creates `.gemini/settings.json` with the correct context mapping:
19
+ ```json
20
+ {
21
+ "context": {
22
+ "fileName": ["AGENTS.md", "GEMINI.md"]
23
+ }
24
+ }
25
+ ```
26
+ - **Antigravity & Claude Code**: Automatically creates symbolic links at `.agent/rules/AGENTS.md` and `.claude/rules/AGENTS.md` pointing to the root rules file.
27
+
14
28
  *Can't find your favorite agent? Submit a PR creating a Kit for it!*
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jeancodogno/specforce-kit",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "SpecForce Kit CLI - Distributed via GoReleaser",
5
5
  "repository": {
6
6
  "type": "git",
@@ -10,7 +10,7 @@ import (
10
10
  "github.com/jeancodogno/specforce-kit/src/internal/cli/cobra"
11
11
  )
12
12
 
13
- var version = "0.1.4"
13
+ var version = "0.1.5"
14
14
 
15
15
  func main() {
16
16
  ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
@@ -35,10 +35,13 @@ Specforce allows developers to gate state transitions (e.g., finishing a task) u
35
35
  ` + "```" + `yaml
36
36
  # config.yaml example
37
37
  hooks:
38
- on_task_finish:
39
- command: "make lint && make test"
40
- on_spec_finish:
41
- command: "make build"
38
+ on_task_finished:
39
+ - "make lint"
40
+ - "make test"
41
+ on_phase_finished:
42
+ - "go test ./src/internal/..."
43
+ on_all_tasks_finished:
44
+ - "go test ./..."
42
45
  ` + "```" + `
43
46
  If a hook fails, the state transition will be blocked.
44
47
 
@@ -77,6 +80,50 @@ func EnsureAgentsMD(root string, ui core.UI) error {
77
80
  return fmt.Errorf("failed to write AGENTS.md: %w", err)
78
81
  }
79
82
 
83
+ return ensurePlatformConfigs(root)
84
+ }
85
+
86
+ func ensurePlatformConfigs(root string) error {
87
+ // 1. Gemini
88
+ geminiDir := filepath.Join(root, ".gemini")
89
+ if err := os.MkdirAll(geminiDir, 0750); err != nil {
90
+ return fmt.Errorf("failed to create .gemini directory: %w", err)
91
+ }
92
+ geminiSettings := filepath.Join(geminiDir, "settings.json")
93
+ settingsContent := `{
94
+ "context": {
95
+ "fileName": [
96
+ "AGENTS.md",
97
+ "GEMINI.md"
98
+ ]
99
+ }
100
+ }`
101
+ // Always write the file to ensure the configuration is correct and up to date
102
+ if err := os.WriteFile(geminiSettings, []byte(settingsContent), 0600); err != nil {
103
+ return fmt.Errorf("failed to write .gemini/settings.json: %w", err)
104
+ }
105
+
106
+ // 2. Symlinks
107
+ agents := []string{".agent", ".claude"}
108
+ for _, agent := range agents {
109
+ rulesDir := filepath.Join(root, agent, "rules")
110
+ if err := os.MkdirAll(rulesDir, 0750); err != nil {
111
+ return fmt.Errorf("failed to create %s/rules directory: %w", agent, err)
112
+ }
113
+
114
+ linkPath := filepath.Join(rulesDir, "AGENTS.md")
115
+ if _, err := os.Lstat(linkPath); err == nil {
116
+ // Remove existing link or file if it exists to ensure it's correct
117
+ if err := os.Remove(linkPath); err != nil {
118
+ return fmt.Errorf("failed to remove existing link at %s: %w", linkPath, err)
119
+ }
120
+ }
121
+
122
+ if err := os.Symlink("../../AGENTS.md", linkPath); err != nil {
123
+ return fmt.Errorf("failed to create symlink at %s: %w", linkPath, err)
124
+ }
125
+ }
126
+
80
127
  return nil
81
128
  }
82
129
 
@@ -54,6 +54,52 @@ func TestEnsureAgentsMD(t *testing.T) {
54
54
  })
55
55
  }
56
56
 
57
+ func TestEnsurePlatformConfigs(t *testing.T) {
58
+ tempDir, err := os.MkdirTemp("", "specforce-test-*")
59
+ if err != nil {
60
+ t.Fatalf("failed to create temp dir: %v", err)
61
+ }
62
+ defer func() { _ = os.RemoveAll(tempDir) }()
63
+
64
+ err = EnsureAgentsMD(tempDir, nil)
65
+ if err != nil {
66
+ t.Errorf("expected no error, got %v", err)
67
+ }
68
+
69
+ // Gemini
70
+ geminiPath := filepath.Join(tempDir, ".gemini", "settings.json")
71
+ if _, err := os.Stat(geminiPath); err != nil {
72
+ t.Errorf("Gemini settings.json not created: %v", err)
73
+ }
74
+ data, _ := os.ReadFile(geminiPath)
75
+ if !strings.Contains(string(data), "\"fileName\": [") {
76
+ t.Errorf("Gemini settings.json content mismatch (expected array): %s", string(data))
77
+ }
78
+ if !strings.Contains(string(data), "\"AGENTS.md\"") {
79
+ t.Errorf("Gemini settings.json missing AGENTS.md: %s", string(data))
80
+ }
81
+
82
+ // Antigravity symlink
83
+ agentLink := filepath.Join(tempDir, ".agent", "rules", "AGENTS.md")
84
+ if _, err := os.Lstat(agentLink); err != nil {
85
+ t.Errorf("Antigravity symlink not created: %v", err)
86
+ }
87
+ target, _ := os.Readlink(agentLink)
88
+ if target != "../../AGENTS.md" {
89
+ t.Errorf("Antigravity symlink target mismatch: %s", target)
90
+ }
91
+
92
+ // Claude Code symlink
93
+ claudeLink := filepath.Join(tempDir, ".claude", "rules", "AGENTS.md")
94
+ if _, err := os.Lstat(claudeLink); err != nil {
95
+ t.Errorf("Claude Code symlink not created: %v", err)
96
+ }
97
+ target, _ = os.Readlink(claudeLink)
98
+ if target != "../../AGENTS.md" {
99
+ t.Errorf("Claude Code symlink target mismatch: %s", target)
100
+ }
101
+ }
102
+
57
103
  func TestGenerateAgentsContent(t *testing.T) {
58
104
  content := generateAgentsContent()
59
105
 
@@ -7,7 +7,7 @@ import (
7
7
  "github.com/charmbracelet/lipgloss"
8
8
  )
9
9
 
10
- var AppVersion = "v0.1.4"
10
+ var AppVersion = "v0.1.5"
11
11
 
12
12
  var brailleLines = []string{
13
13
  ` ⢠⣶⣶⡄ `,