@jeancodogno/specforce-kit 0.1.5 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/index.js +46 -0
- package/package.json +12 -28
- package/.geminiignore +0 -15
- package/.github/workflows/ci.yml +0 -104
- package/.github/workflows/release.yml +0 -51
- package/.golangci.yml +0 -24
- package/.goreleaser.yaml +0 -39
- package/.rgignore +0 -13
- package/.specforce/archive/agents-md-hooks-config/design.md +0 -38
- package/.specforce/archive/agents-md-hooks-config/requirements.md +0 -35
- package/.specforce/archive/agents-md-hooks-config/tasks.md +0 -76
- package/.specforce/config.yaml +0 -32
- package/.specforce/docs/.gitkeep +0 -0
- package/.specforce/docs/architecture.md +0 -98
- package/.specforce/docs/engineering.md +0 -84
- package/.specforce/docs/governance.md +0 -30
- package/.specforce/docs/memorial.md +0 -45
- package/.specforce/docs/principles.md +0 -31
- package/.specforce/docs/security.md +0 -31
- package/.specforce/docs/ui-ux.md +0 -129
- package/.specforce/specs/.gitkeep +0 -0
- package/AGENTS.md +0 -46
- package/CONTRIBUTING.md +0 -81
- package/Makefile +0 -49
- package/assets/logo-header.png +0 -0
- package/assets/logo.png +0 -0
- package/docs/artifacts.md +0 -41
- package/docs/cli.md +0 -73
- package/docs/configuration.md +0 -59
- package/docs/getting-started.md +0 -110
- package/docs/supported-tools.md +0 -28
- package/go.mod +0 -35
- package/go.sum +0 -61
- package/src/cmd/specforce/main.go +0 -23
- package/src/cmd/specforce/main_test.go +0 -7
- package/src/internal/agent/artifacts/constitution/architecture.yaml +0 -70
- package/src/internal/agent/artifacts/constitution/engineering.yaml +0 -52
- package/src/internal/agent/artifacts/constitution/governance.yaml +0 -41
- package/src/internal/agent/artifacts/constitution/memorial.yaml +0 -55
- package/src/internal/agent/artifacts/constitution/principles.yaml +0 -54
- package/src/internal/agent/artifacts/constitution/security.yaml +0 -47
- package/src/internal/agent/artifacts/constitution/ui-ux.yaml +0 -158
- package/src/internal/agent/artifacts/spec/design.yaml +0 -50
- package/src/internal/agent/artifacts/spec/requirements.yaml +0 -48
- package/src/internal/agent/artifacts/spec/tasks.yaml +0 -55
- package/src/internal/agent/compatibility_test.go +0 -120
- package/src/internal/agent/cwd_test.go +0 -9
- package/src/internal/agent/embed.go +0 -19
- package/src/internal/agent/integration_test.go +0 -138
- package/src/internal/agent/kit/agents/product-analyst.yaml +0 -31
- package/src/internal/agent/kit/agents/technical-developer.yaml +0 -28
- package/src/internal/agent/kit/agents/technical-project-planner.yaml +0 -30
- package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +0 -36
- package/src/internal/agent/kit/agents/technical-solution-architect.yaml +0 -32
- package/src/internal/agent/kit/commands/archive.yaml +0 -25
- package/src/internal/agent/kit/commands/constitution.yaml +0 -132
- package/src/internal/agent/kit/commands/implement.yaml +0 -96
- package/src/internal/agent/kit/commands/spec.yaml +0 -94
- package/src/internal/agent/kit/instructions/archive.md +0 -68
- package/src/internal/agent/kit/kit.yaml +0 -111
- package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +0 -56
- package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +0 -58
- package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +0 -38
- package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +0 -52
- package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +0 -137
- package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +0 -103
- package/src/internal/agent/kit_manifests_test.go +0 -58
- package/src/internal/agent/manifest.go +0 -15
- package/src/internal/agent/registry.go +0 -69
- package/src/internal/agent/registry_test.go +0 -51
- package/src/internal/agent/translator.go +0 -334
- package/src/internal/agent/translator_test.go +0 -734
- package/src/internal/cli/archive.go +0 -91
- package/src/internal/cli/archive_test.go +0 -67
- package/src/internal/cli/cli.go +0 -259
- package/src/internal/cli/cli_test.go +0 -130
- package/src/internal/cli/cobra/archive.go +0 -26
- package/src/internal/cli/cobra/console.go +0 -21
- package/src/internal/cli/cobra/constitution.go +0 -44
- package/src/internal/cli/cobra/dummy_test.go +0 -7
- package/src/internal/cli/cobra/implementation.go +0 -50
- package/src/internal/cli/cobra/init.go +0 -23
- package/src/internal/cli/cobra/install.go +0 -21
- package/src/internal/cli/cobra/root.go +0 -47
- package/src/internal/cli/cobra/spec.go +0 -91
- package/src/internal/cli/console.go +0 -48
- package/src/internal/cli/constitution.go +0 -190
- package/src/internal/cli/constitution_test.go +0 -50
- package/src/internal/cli/implementation.go +0 -153
- package/src/internal/cli/implementation_test.go +0 -165
- package/src/internal/cli/spec.go +0 -369
- package/src/internal/cli/spec_test.go +0 -85
- package/src/internal/constitution/registry.go +0 -139
- package/src/internal/constitution/registry_test.go +0 -97
- package/src/internal/constitution/status.go +0 -70
- package/src/internal/constitution/status_test.go +0 -160
- package/src/internal/core/blueprint.go +0 -49
- package/src/internal/core/blueprint_test.go +0 -58
- package/src/internal/core/config.go +0 -124
- package/src/internal/core/config_test.go +0 -145
- package/src/internal/core/constants.go +0 -13
- package/src/internal/core/errors.go +0 -31
- package/src/internal/core/errors_test.go +0 -48
- package/src/internal/core/hooks.go +0 -89
- package/src/internal/core/hooks_test.go +0 -51
- package/src/internal/core/kit.go +0 -15
- package/src/internal/core/kit_test.go +0 -65
- package/src/internal/core/path.go +0 -115
- package/src/internal/core/path_test.go +0 -101
- package/src/internal/core/ui.go +0 -19
- package/src/internal/installer/dependencies.go +0 -23
- package/src/internal/installer/install.go +0 -89
- package/src/internal/installer/installer.go +0 -45
- package/src/internal/installer/installer_test.go +0 -96
- package/src/internal/project/agents_md.go +0 -155
- package/src/internal/project/agents_md_test.go +0 -147
- package/src/internal/project/bootstrapper.go +0 -64
- package/src/internal/project/bootstrapper_test.go +0 -89
- package/src/internal/project/detector.go +0 -35
- package/src/internal/project/detector_test.go +0 -96
- package/src/internal/project/refresh_integration_test.go +0 -86
- package/src/internal/project/service.go +0 -93
- package/src/internal/project/service_test.go +0 -135
- package/src/internal/spec/archive.go +0 -49
- package/src/internal/spec/archive_test.go +0 -55
- package/src/internal/spec/discovery.go +0 -53
- package/src/internal/spec/discovery_test.go +0 -60
- package/src/internal/spec/implementation.go +0 -296
- package/src/internal/spec/implementation_test.go +0 -253
- package/src/internal/spec/registry.go +0 -142
- package/src/internal/spec/registry_test.go +0 -105
- package/src/internal/spec/scanner.go +0 -219
- package/src/internal/spec/scanner_test.go +0 -243
- package/src/internal/spec/service.go +0 -157
- package/src/internal/spec/service_test.go +0 -238
- package/src/internal/spec/status.go +0 -94
- package/src/internal/spec/status_test.go +0 -146
- package/src/internal/spec/tasks.go +0 -103
- package/src/internal/spec/tasks_test.go +0 -137
- package/src/internal/tui/components.go +0 -132
- package/src/internal/tui/console.go +0 -247
- package/src/internal/tui/console_test.go +0 -19
- package/src/internal/tui/constitution.go +0 -36
- package/src/internal/tui/constitution_test.go +0 -32
- package/src/internal/tui/implementation.go +0 -151
- package/src/internal/tui/logo.go +0 -89
- package/src/internal/tui/multiselect.go +0 -199
- package/src/internal/tui/progressbar.go +0 -37
- package/src/internal/tui/progressbar_test.go +0 -30
- package/src/internal/tui/spec.go +0 -35
- package/src/internal/tui/spinner.go +0 -66
- package/src/internal/tui/terminal.go +0 -18
- package/src/internal/tui/theme.go +0 -125
- package/src/internal/tui/ui.go +0 -52
|
@@ -1,84 +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
|
-
- **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).
|
|
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.
|
|
16
|
-
- **Slug Defaulting:** If a mapping's `name` field is empty, the system MUST default to the artifact's slug.
|
|
17
|
-
- **Hierarchy Preservation:** For static mappings (no `*` in path), the system MUST preserve any sub-directory hierarchy found in the source category.
|
|
18
|
-
- **Agent Tool Addition Process:** To integrate a new agent tool into the Specforce ecosystem, developers MUST follow these steps:
|
|
19
|
-
1. **Register Constant:** Add the tool's hidden directory name (e.g., `.newagent/`) to the `ToolPrefixes` slice in `src/internal/core/constants.go`.
|
|
20
|
-
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`).
|
|
21
|
-
3. **Granular Pathing:** Utilize the mapping-level `target` override and environment variable expansion (e.g., `${VAR:-DEFAULT}`) to support global path requirements when necessary.
|
|
22
|
-
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`.
|
|
23
|
-
- **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.
|
|
24
|
-
- **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.
|
|
25
|
-
- **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.
|
|
26
|
-
- **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.
|
|
27
|
-
- **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.
|
|
28
|
-
- **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).
|
|
29
|
-
- **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.
|
|
30
|
-
- **Complexity Limits:** Maximum function length: 50 lines. Maximum cyclomatic complexity: 10 per function.
|
|
31
|
-
- **Refactoring Patterns:**
|
|
32
|
-
- **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.
|
|
33
|
-
- **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.
|
|
34
|
-
- **Permission Hardening:** All I/O operations MUST use the most restrictive permissions possible:
|
|
35
|
-
- **Directories:** Use `0750` for all directory creation (`os.MkdirAll`).
|
|
36
|
-
- **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.
|
|
37
|
-
|
|
38
|
-
- **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.
|
|
39
|
-
- **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.
|
|
40
|
-
|
|
41
|
-
## Agent Orchestration Protocol
|
|
42
|
-
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.
|
|
43
|
-
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.
|
|
44
|
-
3. **Primary Orchestration Only:** Agents MUST remain in their primary orchestration loop and NOT use specialized "plan" or "design" modes for requirement discovery.
|
|
45
|
-
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.
|
|
46
|
-
5. **Binary-Path Standard:** All agent-triggered CLI commands MUST use the global binary `specforce` (not `./specforce`) to ensure cross-platform consistency.
|
|
47
|
-
|
|
48
|
-
## Context Handling
|
|
49
|
-
- **Mandatory Propagation:** All functions performing I/O, recursion, or loops MUST accept `context.Context` as their first argument.
|
|
50
|
-
- **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.
|
|
51
|
-
- *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.
|
|
52
|
-
- **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.
|
|
53
|
-
|
|
54
|
-
## Testing Strategy
|
|
55
|
-
- **Frameworks:** Standard Go `testing` package; optional use of `stretchr/testify` for assertions.
|
|
56
|
-
- **Coverage Gate:** 80% minimum coverage for core domain packages (`src/internal/core`, `src/internal/project`, `src/internal/spec`).
|
|
57
|
-
- **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).
|
|
58
|
-
- **Unit Testing Rules:** All core logic and state transitions MUST have automated unit tests.
|
|
59
|
-
- **Regression Rules:** Any reported bug MUST be reproduced with a failing test case before being fixed.
|
|
60
|
-
|
|
61
|
-
## Delivery Standards & DoD
|
|
62
|
-
- **Commit Standard:** Conventional Commits (e.g., `feat:`, `fix:`, `docs:`, `chore:`).
|
|
63
|
-
- **Continuous Integration:** PRs MUST trigger a multi-job parallel pipeline (Lint, Security, Test, Quality) for rapid feedback.
|
|
64
|
-
- **Security Scans:** Security checks MUST use `gosec` and `govulncheck`. Findings MUST be reported via SARIF to the GitHub Security tab.
|
|
65
|
-
- **Definition of Done (DoD):**
|
|
66
|
-
- [ ] Code passes `golangci-lint` and `go test`.
|
|
67
|
-
- [ ] Coverage gate is met or maintained.
|
|
68
|
-
- [ ] Security scans pass (zero critical findings).
|
|
69
|
-
- [ ] TUI views are manually verified for layout consistency.
|
|
70
|
-
- [ ] Feature Specification status is updated to "Implemented".
|
|
71
|
-
- [ ] The Memorial is updated with relevant "Last Actions".
|
|
72
|
-
|
|
73
|
-
## Error Handling Standards
|
|
74
|
-
- **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.
|
|
75
|
-
- **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.
|
|
76
|
-
- **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.
|
|
77
|
-
- **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.
|
|
78
|
-
- **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.
|
|
79
|
-
|
|
80
|
-
## Specification & Task Organization
|
|
81
|
-
- **Hierarchical Task Structure:** Implementation roadmaps (`tasks.md`) MUST use a hierarchical structure to group atomic tasks.
|
|
82
|
-
- **Phases (H3):** Use `### Phase {N}: {Title}` for logical groupings.
|
|
83
|
-
- **Tasks (H4):** Use `#### T{Phase}.{Task}: {Title}` for individual implementation steps.
|
|
84
|
-
- **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,45 +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
|
-
- [2026-04-26] [Linter] `.golangci.yml` requires `version: "2"` for compatibility with current `golangci-lint` versions.
|
|
20
|
-
|
|
21
|
-
## Last Actions
|
|
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
|
|
27
|
-
|
|
28
|
-
## Active Lessons & Anti-Patterns
|
|
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
|
|
38
|
-
|
|
39
|
-
## Pending Decisions (Need Distillation)
|
|
40
|
-
- **Date:**
|
|
41
|
-
- **Scope:**
|
|
42
|
-
- **Decision:**
|
|
43
|
-
- **Why:**
|
|
44
|
-
- **Validate By:**
|
|
45
|
-
- **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.
|
package/.specforce/docs/ui-ux.md
DELETED
|
@@ -1,129 +0,0 @@
|
|
|
1
|
-
# UI/UX
|
|
2
|
-
|
|
3
|
-
## 1. Visual Theme & Atmosphere
|
|
4
|
-
- **Framework/Base:** Bubbletea (TUI) with Lipgloss for styling.
|
|
5
|
-
- **Theme:** Ghost in the Machine.
|
|
6
|
-
- **Atmosphere:** Surgical, alien, and extremely clean. Conveys the idea of an autonomous agent working flawlessly.
|
|
7
|
-
- **Density Posture:** Compact (Optimized for standard terminal dimensions).
|
|
8
|
-
- **Design Philosophy:** Optimizes for readability and fast keyboard navigation; avoids unnecessary visual clutter.
|
|
9
|
-
- **Signature Moves:** Consistent "Branding" boxes, ASCII art logos (Braille-based), and color-coded status indicators. Minimalist separators instead of thick borders.
|
|
10
|
-
|
|
11
|
-
## 2. Color Palette & Roles
|
|
12
|
-
### Brand & Accent
|
|
13
|
-
- **Primary Brand:** `#00FA9A` (Mint Green) | Primary borders, brand name, and major headings.
|
|
14
|
-
- **Secondary Brand:** `#00FFFF` (Cyan) | Subheadings and active selection highlights.
|
|
15
|
-
- **Accent:** `#E0FFFF` (Silver/Ice) | Muted subtitles and special focus elements.
|
|
16
|
-
|
|
17
|
-
### Text & Feedback
|
|
18
|
-
- **Primary Text:** `#FFFFFF` | Standard body text and labels.
|
|
19
|
-
- **Secondary Text / Metadata:** `#808080` | Muted information, metadata, captions, and pending items.
|
|
20
|
-
- **Error:** `#FF5F5F` | Critical failures, validation errors, and destructive actions.
|
|
21
|
-
- **Success / Done:** `#5FFF87` | Successful operations and completed items (`◉`).
|
|
22
|
-
- **Warning / In-Progress:** `#FFFFAF` | Non-critical alerts and active/working items (`◉`).
|
|
23
|
-
- **Info:** `#87AFFF` | Informational messages and help context.
|
|
24
|
-
|
|
25
|
-
### Iconography & Status States
|
|
26
|
-
- **Done:** `◉` (Filled Circle) in **Success Green** (`#5FFF87`).
|
|
27
|
-
- **In-Progress:** `◉` (Filled Circle) in **Warning/Orange** (`#FFFFAF`).
|
|
28
|
-
- **Pending / Inactive:** `○` (Empty Circle) in **Secondary Gray** (`#808080`).
|
|
29
|
-
- **Description / Context:** `↳` (Right Arrow) in **Secondary Gray** (`#808080`) for indented details.
|
|
30
|
-
|
|
31
|
-
### Surface & Border
|
|
32
|
-
- **Canvas:** `#000000` | Terminal background.
|
|
33
|
-
- **Surface:** `#121212` | Highlighted block backgrounds.
|
|
34
|
-
- **Muted Surface:** `#080808` | Secondary block backgrounds.
|
|
35
|
-
- **Border:** `#444444` | Standard UI borders, preferring thin or dashed lines.
|
|
36
|
-
|
|
37
|
-
## 3. Typography Rules
|
|
38
|
-
### Font Family
|
|
39
|
-
- **Primary:** Monospace (System Default).
|
|
40
|
-
- **Secondary:** N/A.
|
|
41
|
-
- **Usage Logic:** Hierarchy is strictly created via color, weight (bold), and whitespace.
|
|
42
|
-
|
|
43
|
-
### Hierarchy
|
|
44
|
-
| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
|
|
45
|
-
|---|---|---|---|---|---|---|
|
|
46
|
-
| Display | Monospace | N/A | Bold | N/A | N/A | Brand/Logo |
|
|
47
|
-
| Heading | Monospace | N/A | Bold | N/A | N/A | Primary sections |
|
|
48
|
-
| Subheading | Monospace | N/A | Normal | N/A | N/A | Secondary sections |
|
|
49
|
-
| Body | Monospace | N/A | Normal | N/A | N/A | Content text |
|
|
50
|
-
| UI Label | Monospace | N/A | Bold | N/A | N/A | Input labels |
|
|
51
|
-
| Caption | Monospace | N/A | Normal | N/A | N/A | Muted metadata |
|
|
52
|
-
|
|
53
|
-
### Content Voice
|
|
54
|
-
- **Headlines:** Direct and imperative.
|
|
55
|
-
- **Buttons & Actions:** Clear and concise (e.g., [ Confirm ], [ Cancel ]).
|
|
56
|
-
- **Form Guidance:** Helpful and instructional.
|
|
57
|
-
|
|
58
|
-
## 4. Component Stylings
|
|
59
|
-
### Buttons
|
|
60
|
-
- **Primary:** High-contrast text or inverted colors (e.g., `[ Confirm ]`).
|
|
61
|
-
- **Secondary:** Standard text within brackets (e.g., `[ Back ]`).
|
|
62
|
-
- **Destructive:** Red text or background.
|
|
63
|
-
|
|
64
|
-
### Cards & Panels
|
|
65
|
-
- **Container Style:** Lipgloss `Normal` or custom clean separators (e.g., `-` and `|` with `+` corners). Avoid `Thick` borders.
|
|
66
|
-
- **State Behavior:** Borders change color based on focus or status (e.g., Mint Green for active).
|
|
67
|
-
|
|
68
|
-
### Inputs & Forms
|
|
69
|
-
- **Input Baseline:** Clear prefix (e.g., `> ` or `? `).
|
|
70
|
-
- **Focus Style:** Cursor highlight or colored prefix.
|
|
71
|
-
- **Error Style:** Red text below the input.
|
|
72
|
-
|
|
73
|
-
### Navigation
|
|
74
|
-
- **Primary Navigation:** List-based selection with cursor indicator.
|
|
75
|
-
- **Active State:** Cyan or Mint Green highlight.
|
|
76
|
-
- **Secondary Navigation:** Footer shortcuts (e.g., `esc: back • q: quit`).
|
|
77
|
-
|
|
78
|
-
## 5. Layout Principles
|
|
79
|
-
- **Spacing Scale:** 1-character/line baseline grid.
|
|
80
|
-
- **Grid Logic:** Strictly vertical stacking with 1-line internal padding.
|
|
81
|
-
- **Whitespace Philosophy:** Use empty lines to separate logical contexts.
|
|
82
|
-
- **Page Structure Bias:** Centered or Left-aligned with a fixed width for core content.
|
|
83
|
-
- **Navigation Distribution:** Persistent footer for global actions.
|
|
84
|
-
|
|
85
|
-
## 6. Depth & Elevation
|
|
86
|
-
| Level | Treatment | Use |
|
|
87
|
-
|---|---|---|
|
|
88
|
-
| Flat | No border | Backgrounds, passive surfaces |
|
|
89
|
-
| Raised | Single border | Cards, status blocks |
|
|
90
|
-
| Interactive Hover | Highlighted text | Active menu items, buttons |
|
|
91
|
-
| Modal / Priority | Clean solid border | Dialogs, progress bars, blocking UI |
|
|
92
|
-
|
|
93
|
-
- **Shadow Philosophy:** N/A (TUI).
|
|
94
|
-
- **Surface Hierarchy:** Higher priority elements use brighter border colors.
|
|
95
|
-
|
|
96
|
-
## 7. Do's and Don'ts
|
|
97
|
-
### Do
|
|
98
|
-
- Use consistent ASCII art branding across all major views.
|
|
99
|
-
- Ensure all interactive elements provide visual feedback on focus.
|
|
100
|
-
- Adhere to the 80-character width standard for core content.
|
|
101
|
-
|
|
102
|
-
### Don't
|
|
103
|
-
- Use blinking text or excessive flashing colors.
|
|
104
|
-
- Depend on mouse-only interactions.
|
|
105
|
-
- Overcrowd a single screen; use scrolling or multi-step wizards.
|
|
106
|
-
|
|
107
|
-
## 8. Responsive Behavior
|
|
108
|
-
| Breakpoint | Width | Key Changes |
|
|
109
|
-
|---|---|---|
|
|
110
|
-
| Mobile | < 40 chars | Minimalist mode; single-column only. |
|
|
111
|
-
| Tablet | < 80 chars | Compact mode; standard layout. |
|
|
112
|
-
| Desktop | > 80 chars | Expanded mode; sidebars allowed. |
|
|
113
|
-
| Large Desktop | > 120 chars | Maximum readability; additional gutters. |
|
|
114
|
-
|
|
115
|
-
- **Touch Targets:** N/A (Keyboard-centric).
|
|
116
|
-
- **Collapsing Strategy:** Hide non-essential metadata on small terminals.
|
|
117
|
-
- **Responsive Priority:** Command inputs and core status are prioritized.
|
|
118
|
-
|
|
119
|
-
## 9. Agent Prompt Guide
|
|
120
|
-
### Quick Reference
|
|
121
|
-
- **Theme Summary:** Ghost in the Machine (TUI).
|
|
122
|
-
- **Primary Colors:** Mint Green (#00FA9A), Cyan (#00FFFF), and Silver/Ice (#E0FFFF).
|
|
123
|
-
- **Typography Summary:** Monospace only; hierarchy via weight/color.
|
|
124
|
-
- **Key Surface Rules:** Borders define depth; spacing defines context. Prefer thin/clean lines over thick borders.
|
|
125
|
-
|
|
126
|
-
### Example Prompts
|
|
127
|
-
- "Build a TUI component using Lipgloss that represents a project status card with a thin Mint Green border and a green success label."
|
|
128
|
-
- "Build a Bubbletea form for gathering user input, ensuring the prompt prefix changes to red on validation failure."
|
|
129
|
-
- "When designing this TUI layout, ensure it remains readable on an 80x24 terminal by using vertical stacking and minimal padding."
|
|
File without changes
|
package/AGENTS.md
DELETED
|
@@ -1,46 +0,0 @@
|
|
|
1
|
-
<!-- SPECFORCE_AGENTS_START -->
|
|
2
|
-
# AI Agent Collaboration Guide
|
|
3
|
-
|
|
4
|
-
This project uses **Specforce** for Spec-Driven Development (SDD). As an AI agent, you MUST adhere to the following rules:
|
|
5
|
-
|
|
6
|
-
## 1. Spec-Driven Development (SDD) Protocol
|
|
7
|
-
- **Specs First:** Never write implementation code until a corresponding Specification (requirements.md, design.md, tasks.md) exists and is approved. You MUST consult spec artifacts using the Specforce CLI (e.g., specforce spec list, specforce spec status <slug> --json, and specforce spec artifact <name> --json) rather than reading the raw markdown files directly.
|
|
8
|
-
- **Atomic Tasks:** Follow the exact sequence of the tasks.md roadmap. Mark tasks as [DONE] or [FINISHED] sequentially.
|
|
9
|
-
- **Verification:** Execute the exact verification/TDD steps defined in the tasks.md file before marking a task as complete.
|
|
10
|
-
|
|
11
|
-
## 2. Project Constitution
|
|
12
|
-
Before proposing architectural changes or adding new patterns, you MUST review the relevant Constitution documents located in .specforce/docs/:
|
|
13
|
-
- principles.md: Core values, philosophy, and cultural/technical axioms.
|
|
14
|
-
- architecture.md: System boundaries, dependency direction, and persistence topology.
|
|
15
|
-
- ui-ux.md: Visual direction, interaction patterns, and aesthetic DNA.
|
|
16
|
-
- security.md: AuthZ, roles, permissions, and data protection rules.
|
|
17
|
-
- engineering.md: Coding standards, testing strategy, and refactoring guidelines.
|
|
18
|
-
- governance.md: Project lifecycle rules, ownership, and AI boundaries.
|
|
19
|
-
- memorial.md: Durable lessons learned and cross-session memory.
|
|
20
|
-
|
|
21
|
-
## 3. Custom Hooks Configuration
|
|
22
|
-
Specforce allows developers to gate state transitions (e.g., finishing a task) using custom hooks. You can configure these in the project root's config.yaml:
|
|
23
|
-
|
|
24
|
-
```yaml
|
|
25
|
-
# config.yaml example
|
|
26
|
-
hooks:
|
|
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 ./..."
|
|
34
|
-
```
|
|
35
|
-
If a hook fails, the state transition will be blocked.
|
|
36
|
-
|
|
37
|
-
*Note: The content above is managed by Specforce. Do not edit inside these markers.*
|
|
38
|
-
<!-- SPECFORCE_AGENTS_END -->
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
package/CONTRIBUTING.md
DELETED
|
@@ -1,81 +0,0 @@
|
|
|
1
|
-
# Contributing to Specforce Kit
|
|
2
|
-
|
|
3
|
-
First off, thank you for considering contributing to Specforce Kit! It's people like you that make Specforce a great tool for the entire AI-Engineering community.
|
|
4
|
-
|
|
5
|
-
## 🚀 Our Philosophy: Spec-First
|
|
6
|
-
We drink our own champagne. **All new features, bug fixes, or architectural changes in this repository MUST follow the Spec-Driven Development (SDD) lifecycle.**
|
|
7
|
-
|
|
8
|
-
1. **Specification:** Every change starts with a Spec via your AI agent (`/spf:spec`).
|
|
9
|
-
2. **Implementation:** Once approved, we implement using the Specforce roadmap (`/spf:implement`).
|
|
10
|
-
3. **Verification & Archive:** Automated tests and manual TUI verification are mandatory before closing the loop (`/spf:archive`).
|
|
11
|
-
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
## 🐛 Reporting Issues
|
|
15
|
-
|
|
16
|
-
### Bug Reports
|
|
17
|
-
- Use the GitHub Issue tracker.
|
|
18
|
-
- Describe the expected behavior vs. actual behavior.
|
|
19
|
-
- Provide a minimal reproduction script or steps.
|
|
20
|
-
- Include your OS and Specforce version (`specforce version`).
|
|
21
|
-
|
|
22
|
-
### Feature Requests
|
|
23
|
-
- We love new ideas! Please open an issue to discuss the "Why" and "Value" before diving into technical details.
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
## 🛠 Pull Request Process
|
|
28
|
-
|
|
29
|
-
1. **Fork and Branch:** Create a feature branch from `main`.
|
|
30
|
-
2. **Create a Spec:** Use your preferred AI agent (Claude Code, Cursor, etc.) and run the `/spf:spec {description}` slash command to generate the `requirements.md`, `design.md`, and `tasks.md`.
|
|
31
|
-
3. **Implement:** Use the `/spf:implement` command to let the agent execute the tasks.
|
|
32
|
-
4. **Code Standards:**
|
|
33
|
-
- Language: Go 1.26+
|
|
34
|
-
- Formatting: `gofmt` is mandatory.
|
|
35
|
-
- Linting: Must pass `golangci-lint`.
|
|
36
|
-
- Standards: Adhere to our project Constitution.
|
|
37
|
-
5. **Tests:** All new logic must have unit tests. Regression tests are required for bug fixes.
|
|
38
|
-
6. **Archive & Commit:** Run `/spf:archive` to update the global Constitution. Use [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`).
|
|
39
|
-
7. **Submit:** Open a PR against the `main` branch. Ensure the CI pipeline passes.
|
|
40
|
-
|
|
41
|
-
---
|
|
42
|
-
|
|
43
|
-
## 🤖 Kit Development (New Agent Support)
|
|
44
|
-
|
|
45
|
-
Specforce Kit is built to be model-agnostic. We welcome contributions that add support for new AI agents or improve existing ones.
|
|
46
|
-
|
|
47
|
-
### What is a Kit?
|
|
48
|
-
A Kit is a set of instructions, rules, and tool mappings that allow an AI agent to interact with the Specforce framework. These are stored in hidden directories to ensure native discovery by the agents (e.g., `.claude/`, `.gemini/`, `.kilocode/`, etc.).
|
|
49
|
-
|
|
50
|
-
### Creating a New Kit
|
|
51
|
-
1. **Define the Instructions:** Create the necessary markdown files (e.g., `SKILL.md`, `commands.md`) that teach the agent how to call `specforce` CLI commands via the slash commands (`/spf:spec`, `/spf:implement`, etc.).
|
|
52
|
-
2. **Ensure Context Segmentation:** Make sure the new agent integration respects our **Segmented Constitution** model, loading only the necessary architecture, UI/UX, or security rules when needed, rather than dumping everything into the context window.
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
## 🏗 Development Environment
|
|
57
|
-
|
|
58
|
-
### Prerequisites
|
|
59
|
-
- Go 1.26+
|
|
60
|
-
- Make
|
|
61
|
-
|
|
62
|
-
### Setup
|
|
63
|
-
```bash
|
|
64
|
-
git clone https://github.com/jeancodogno/specforce-kit.git
|
|
65
|
-
cd specforce-kit
|
|
66
|
-
make build
|
|
67
|
-
make install
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
### Running Tests
|
|
71
|
-
```bash
|
|
72
|
-
make test
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
---
|
|
76
|
-
|
|
77
|
-
## 📜 Code of Conduct
|
|
78
|
-
By participating in this project, you agree to abide by our project's Code of Conduct and maintain a professional and respectful environment for all contributors.
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
<p align="center">Let's build the future of AI-Orchestrated Engineering together.</p>r.</p>
|
package/Makefile
DELETED
|
@@ -1,49 +0,0 @@
|
|
|
1
|
-
BINARY=specforce
|
|
2
|
-
PREFIX ?= /usr/local
|
|
3
|
-
BINDIR = $(PREFIX)/bin
|
|
4
|
-
|
|
5
|
-
# Go paths
|
|
6
|
-
GOPATH=$(shell go env GOPATH)
|
|
7
|
-
GOBIN=$(GOPATH)/bin
|
|
8
|
-
|
|
9
|
-
build:
|
|
10
|
-
go build -o $(BINARY) src/cmd/specforce/main.go
|
|
11
|
-
|
|
12
|
-
install: build
|
|
13
|
-
install -d $(DESTDIR)$(BINDIR)
|
|
14
|
-
install -m 755 $(BINARY) $(DESTDIR)$(BINDIR)/$(BINARY)
|
|
15
|
-
|
|
16
|
-
uninstall:
|
|
17
|
-
rm -f $(DESTDIR)$(BINDIR)/$(BINARY)
|
|
18
|
-
|
|
19
|
-
test-coverage:
|
|
20
|
-
go test -v -coverprofile=coverage.out ./...
|
|
21
|
-
|
|
22
|
-
test:
|
|
23
|
-
go test ./...
|
|
24
|
-
|
|
25
|
-
lint:
|
|
26
|
-
golangci-lint run ./...
|
|
27
|
-
|
|
28
|
-
security:
|
|
29
|
-
$(GOBIN)/gosec -exclude=G703,G304,G306 -fmt=sarif -out=results.sarif ./...
|
|
30
|
-
$(GOBIN)/govulncheck ./... > /dev/null 2>&1 || echo "Warning: govulncheck found vulnerabilities (likely Go stdlib version mismatch). Ignored locally."
|
|
31
|
-
|
|
32
|
-
quality:
|
|
33
|
-
$(GOBIN)/gremlins unleash
|
|
34
|
-
|
|
35
|
-
quality-lived:
|
|
36
|
-
$(GOBIN)/gremlins unleash -S l
|
|
37
|
-
|
|
38
|
-
check: lint security test quality
|
|
39
|
-
|
|
40
|
-
bootstrap:
|
|
41
|
-
go install github.com/securego/gosec/v2/cmd/gosec@latest
|
|
42
|
-
go install golang.org/x/vuln/cmd/govulncheck@latest
|
|
43
|
-
go install github.com/go-gremlins/gremlins/cmd/gremlins@latest
|
|
44
|
-
|
|
45
|
-
clean-test:
|
|
46
|
-
rm -rf test-init/.specforce test-init/.agent test-init/.claude test-init/.gemini
|
|
47
|
-
rm -f results.sarif coverage.out
|
|
48
|
-
|
|
49
|
-
.PHONY: build test lint security quality check bootstrap clean-test install uninstall
|
package/assets/logo-header.png
DELETED
|
Binary file
|
package/assets/logo.png
DELETED
|
Binary file
|
package/docs/artifacts.md
DELETED
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
# Specforce Artifacts
|
|
2
|
-
|
|
3
|
-
To efficiently orchestrate AI agents and avoid the accumulation of unnecessary context, Specforce divides the project's knowledge into different documents, known as **Artifacts**.
|
|
4
|
-
|
|
5
|
-
## 1. Constitution Artifacts (`docs/`)
|
|
6
|
-
|
|
7
|
-
Located in your project's `docs/` directory, these files form the **Global Constitution**. They contain the vital rules of the system:
|
|
8
|
-
|
|
9
|
-
- **`architecture.md`**: Architecture patterns, directory structure, database choices, and data flows.
|
|
10
|
-
- **`engineering.md`**: Developer environment setup, coding standards, testing strategies, and CI/CD pipelines.
|
|
11
|
-
- **`governance.md`**: Project boundaries, non-goals, long-term technical vision, and decision-making processes.
|
|
12
|
-
- **`memorial.md`**: An automated log maintained by the AI agent containing past technical decisions, key learnings, and systemic context accumulated over time.
|
|
13
|
-
- **`principles.md`**: The core philosophy of the team or project, guiding the agent's general decisions.
|
|
14
|
-
- **`security.md`**: Mandatory security practices, password handling, and sensitive data management.
|
|
15
|
-
- **`ui-ux.md`**: (If applicable) Visual patterns, color palette, accessible components, and interface behaviors.
|
|
16
|
-
|
|
17
|
-
These files are not read all at once. Specforce injects specific context into the agent only when it needs to execute a related task.
|
|
18
|
-
|
|
19
|
-
## 2. Specification Artifacts (`.specforce/specs/<name>/`)
|
|
20
|
-
|
|
21
|
-
When you start a new feature (with `/spf:spec`), the agent creates a focused and temporary "specification package" with the following files:
|
|
22
|
-
|
|
23
|
-
### `requirements.md`
|
|
24
|
-
The definition of the "What". It contains user stories, acceptance criteria (often using BDD syntax like GIVEN/WHEN/THEN), and business constraints.
|
|
25
|
-
|
|
26
|
-
### `design.md`
|
|
27
|
-
The definition of the "How". It contains the technical solution diagram, changes to databases or APIs, and the classes that will be created or altered. No final code is written here, only structural planning.
|
|
28
|
-
|
|
29
|
-
### `tasks.md`
|
|
30
|
-
The atomic "Roadmap". It is the decomposition of `design.md` into actionable technical steps of 5 to 20 minutes. Each task must have a **verification** criterion (e.g., a specific test command the agent will run to prove the task worked).
|
|
31
|
-
|
|
32
|
-
## 3. The `.specforce/` Directory
|
|
33
|
-
|
|
34
|
-
The root `.specforce/` folder maintains the orchestration state. It should generally not be edited manually, with the exception of the configuration file:
|
|
35
|
-
|
|
36
|
-
- **`config.yaml`**: Where you customize validation hooks and advanced instructions (read more in [Configuration](configuration.md)).
|
|
37
|
-
- **`archive/`**: Where finished specifications are stored after running `/spf:archive`, maintaining the history of the application's technical decisions.
|
|
38
|
-
|
|
39
|
-
---
|
|
40
|
-
|
|
41
|
-
Maintaining the quality of these artifacts is the best way to ensure the AI produces excellent code.
|