@jeancodogno/specforce-kit 0.1.0

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 (153) hide show
  1. package/.geminiignore +15 -0
  2. package/.github/workflows/ci.yml +100 -0
  3. package/.github/workflows/release.yml +51 -0
  4. package/.golangci.yml +21 -0
  5. package/.goreleaser.yaml +43 -0
  6. package/.rgignore +13 -0
  7. package/.specforce/config.yaml +32 -0
  8. package/.specforce/docs/.gitkeep +0 -0
  9. package/.specforce/docs/architecture.md +98 -0
  10. package/.specforce/docs/engineering.md +80 -0
  11. package/.specforce/docs/governance.md +30 -0
  12. package/.specforce/docs/memorial.md +44 -0
  13. package/.specforce/docs/principles.md +31 -0
  14. package/.specforce/docs/security.md +31 -0
  15. package/.specforce/docs/ui-ux.md +129 -0
  16. package/.specforce/specs/.gitkeep +0 -0
  17. package/AGENTS.md +36 -0
  18. package/CONTRIBUTING.md +81 -0
  19. package/LICENSE +21 -0
  20. package/Makefile +49 -0
  21. package/README.md +144 -0
  22. package/assets/logo-header.png +0 -0
  23. package/assets/logo.png +0 -0
  24. package/docs/artifacts.md +41 -0
  25. package/docs/cli.md +73 -0
  26. package/docs/configuration.md +50 -0
  27. package/docs/getting-started.md +110 -0
  28. package/docs/supported-tools.md +14 -0
  29. package/go.mod +35 -0
  30. package/go.sum +61 -0
  31. package/index.js +0 -0
  32. package/package.json +26 -0
  33. package/src/cmd/specforce/main.go +23 -0
  34. package/src/cmd/specforce/main_test.go +7 -0
  35. package/src/internal/agent/artifacts/constitution/architecture.yaml +70 -0
  36. package/src/internal/agent/artifacts/constitution/engineering.yaml +52 -0
  37. package/src/internal/agent/artifacts/constitution/governance.yaml +41 -0
  38. package/src/internal/agent/artifacts/constitution/memorial.yaml +55 -0
  39. package/src/internal/agent/artifacts/constitution/principles.yaml +54 -0
  40. package/src/internal/agent/artifacts/constitution/security.yaml +47 -0
  41. package/src/internal/agent/artifacts/constitution/ui-ux.yaml +158 -0
  42. package/src/internal/agent/artifacts/spec/design.yaml +50 -0
  43. package/src/internal/agent/artifacts/spec/requirements.yaml +48 -0
  44. package/src/internal/agent/artifacts/spec/tasks.yaml +55 -0
  45. package/src/internal/agent/compatibility_test.go +120 -0
  46. package/src/internal/agent/cwd_test.go +9 -0
  47. package/src/internal/agent/embed.go +19 -0
  48. package/src/internal/agent/integration_test.go +138 -0
  49. package/src/internal/agent/kit/agents/product-analyst.yaml +31 -0
  50. package/src/internal/agent/kit/agents/technical-developer.yaml +28 -0
  51. package/src/internal/agent/kit/agents/technical-project-planner.yaml +30 -0
  52. package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +36 -0
  53. package/src/internal/agent/kit/agents/technical-solution-architect.yaml +32 -0
  54. package/src/internal/agent/kit/commands/archive.yaml +25 -0
  55. package/src/internal/agent/kit/commands/constitution.yaml +132 -0
  56. package/src/internal/agent/kit/commands/implement.yaml +96 -0
  57. package/src/internal/agent/kit/commands/spec.yaml +94 -0
  58. package/src/internal/agent/kit/instructions/archive.md +68 -0
  59. package/src/internal/agent/kit/kit.yaml +111 -0
  60. package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +56 -0
  61. package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +58 -0
  62. package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +38 -0
  63. package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +52 -0
  64. package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +137 -0
  65. package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +103 -0
  66. package/src/internal/agent/kit_manifests_test.go +58 -0
  67. package/src/internal/agent/manifest.go +15 -0
  68. package/src/internal/agent/registry.go +69 -0
  69. package/src/internal/agent/registry_test.go +51 -0
  70. package/src/internal/agent/translator.go +334 -0
  71. package/src/internal/agent/translator_test.go +734 -0
  72. package/src/internal/cli/archive.go +91 -0
  73. package/src/internal/cli/archive_test.go +67 -0
  74. package/src/internal/cli/cli.go +259 -0
  75. package/src/internal/cli/cli_test.go +130 -0
  76. package/src/internal/cli/cobra/archive.go +26 -0
  77. package/src/internal/cli/cobra/console.go +21 -0
  78. package/src/internal/cli/cobra/constitution.go +44 -0
  79. package/src/internal/cli/cobra/dummy_test.go +7 -0
  80. package/src/internal/cli/cobra/implementation.go +50 -0
  81. package/src/internal/cli/cobra/init.go +23 -0
  82. package/src/internal/cli/cobra/install.go +21 -0
  83. package/src/internal/cli/cobra/root.go +47 -0
  84. package/src/internal/cli/cobra/spec.go +91 -0
  85. package/src/internal/cli/console.go +48 -0
  86. package/src/internal/cli/constitution.go +190 -0
  87. package/src/internal/cli/constitution_test.go +50 -0
  88. package/src/internal/cli/implementation.go +153 -0
  89. package/src/internal/cli/implementation_test.go +165 -0
  90. package/src/internal/cli/spec.go +369 -0
  91. package/src/internal/cli/spec_test.go +85 -0
  92. package/src/internal/constitution/registry.go +139 -0
  93. package/src/internal/constitution/registry_test.go +97 -0
  94. package/src/internal/constitution/status.go +70 -0
  95. package/src/internal/constitution/status_test.go +160 -0
  96. package/src/internal/core/blueprint.go +49 -0
  97. package/src/internal/core/blueprint_test.go +58 -0
  98. package/src/internal/core/config.go +124 -0
  99. package/src/internal/core/config_test.go +145 -0
  100. package/src/internal/core/constants.go +13 -0
  101. package/src/internal/core/errors.go +31 -0
  102. package/src/internal/core/errors_test.go +48 -0
  103. package/src/internal/core/hooks.go +89 -0
  104. package/src/internal/core/hooks_test.go +51 -0
  105. package/src/internal/core/kit.go +15 -0
  106. package/src/internal/core/kit_test.go +65 -0
  107. package/src/internal/core/path.go +115 -0
  108. package/src/internal/core/path_test.go +101 -0
  109. package/src/internal/core/ui.go +19 -0
  110. package/src/internal/installer/dependencies.go +23 -0
  111. package/src/internal/installer/install.go +89 -0
  112. package/src/internal/installer/installer.go +45 -0
  113. package/src/internal/installer/installer_test.go +96 -0
  114. package/src/internal/project/agents_md.go +108 -0
  115. package/src/internal/project/agents_md_test.go +101 -0
  116. package/src/internal/project/bootstrapper.go +64 -0
  117. package/src/internal/project/bootstrapper_test.go +89 -0
  118. package/src/internal/project/detector.go +35 -0
  119. package/src/internal/project/detector_test.go +96 -0
  120. package/src/internal/project/refresh_integration_test.go +86 -0
  121. package/src/internal/project/service.go +93 -0
  122. package/src/internal/project/service_test.go +135 -0
  123. package/src/internal/spec/archive.go +49 -0
  124. package/src/internal/spec/archive_test.go +55 -0
  125. package/src/internal/spec/discovery.go +53 -0
  126. package/src/internal/spec/discovery_test.go +60 -0
  127. package/src/internal/spec/implementation.go +296 -0
  128. package/src/internal/spec/implementation_test.go +253 -0
  129. package/src/internal/spec/registry.go +142 -0
  130. package/src/internal/spec/registry_test.go +105 -0
  131. package/src/internal/spec/scanner.go +219 -0
  132. package/src/internal/spec/scanner_test.go +243 -0
  133. package/src/internal/spec/service.go +157 -0
  134. package/src/internal/spec/service_test.go +238 -0
  135. package/src/internal/spec/status.go +94 -0
  136. package/src/internal/spec/status_test.go +146 -0
  137. package/src/internal/spec/tasks.go +103 -0
  138. package/src/internal/spec/tasks_test.go +137 -0
  139. package/src/internal/tui/components.go +132 -0
  140. package/src/internal/tui/console.go +247 -0
  141. package/src/internal/tui/console_test.go +19 -0
  142. package/src/internal/tui/constitution.go +36 -0
  143. package/src/internal/tui/constitution_test.go +32 -0
  144. package/src/internal/tui/implementation.go +151 -0
  145. package/src/internal/tui/logo.go +89 -0
  146. package/src/internal/tui/multiselect.go +199 -0
  147. package/src/internal/tui/progressbar.go +37 -0
  148. package/src/internal/tui/progressbar_test.go +30 -0
  149. package/src/internal/tui/spec.go +35 -0
  150. package/src/internal/tui/spinner.go +66 -0
  151. package/src/internal/tui/terminal.go +18 -0
  152. package/src/internal/tui/theme.go +125 -0
  153. package/src/internal/tui/ui.go +52 -0
@@ -0,0 +1,56 @@
1
+ name: opportunity-framing
2
+ description: Use during discovery and brainstorming to frame the objective, constraints,
3
+ idea directions, tradeoffs, and next-step recommendations before writing a feature
4
+ spec.
5
+ version: 1.0
6
+ priority: HIGH
7
+ content: '# Opportunity Framing
8
+
9
+
10
+ > **CORE MANDATE:** Turn raw ideas into decision-ready directions, not generic suggestion
11
+ lists.
12
+
13
+
14
+ ## When to use this skill
15
+
16
+ Use for discovery, brainstorming, strategic exploration, idea ranking, and pre-spec
17
+ product framing.
18
+
19
+
20
+ ## How to use it
21
+
22
+ 1. Frame the objective, actor, and outcome clearly.
23
+
24
+ 2. Generate a small number of differentiated directions with tradeoffs.
25
+
26
+ 3. Rank the best options and recommend the next action.
27
+
28
+
29
+ ## Checklist
30
+
31
+ - [ ] The problem framing is explicit.
32
+
33
+ - [ ] Idea directions are meaningfully different.
34
+
35
+ - [ ] Tradeoffs and open questions are visible.
36
+
37
+ - [ ] The recommendation includes a concrete next command.
38
+
39
+
40
+ ## Output Shape
41
+
42
+ - Objective
43
+
44
+ - Constraints
45
+
46
+ - 3-7 idea directions
47
+
48
+ - Top insights
49
+
50
+ - Ranked recommendation
51
+
52
+ - Open questions
53
+
54
+ - Next step
55
+
56
+ '
@@ -0,0 +1,58 @@
1
+ name: pragmatic-product-owner
2
+ description: Use when creating or refining requirements, acceptance criteria, and
3
+ business success metrics. Optimizes clarity, testability, and value-focused scope.
4
+ version: 1.0
5
+ priority: CRITICAL
6
+ content: "# Pragmatic Product Owner\n\n> **CORE MANDATE:** Maximize the value of the\
7
+ \ product. Every requirement must be verifiable through clear Acceptance Criteria.\n\
8
+ \n---\n\n## When to use this skill\nUse for requirements, acceptance criteria, business\
9
+ \ rules, key entities, scope cuts, and measurable outcomes.\n\n## How to use it\n\
10
+ 1. Clarify user value, actor, and business constraint first.\n2. Write binary acceptance\
11
+ \ criteria and independent tests.\n3. Check the spec is valuable, testable, and\
12
+ \ free of solution leakage.\n\n## Checklist\n- [ ] Requirements describe outcomes,\
13
+ \ not implementation.\n- [ ] Acceptance criteria are pass/fail and independently\
14
+ \ testable.\n- [ ] Success criteria are measurable and worth building.\n\n## Artifact\
15
+ \ Guidance\n- **For discovery/brainstorming**: frame the problem, constraints, insight\
16
+ \ quality, and decision-ready next steps before turning ideas into features.\n-\
17
+ \ **For `requirements.md`**: define value, persona, entities, golden rules, measurable\
18
+ \ outcomes, and independent tests.\n- **For clarification loops**: resolve ambiguity\
19
+ \ by making business decisions explicit in the source requirement, not in side notes\
20
+ \ only.\n\n## References\n- **Spec artifacts and requirement shaping**: read [spec-artifacts.md](references/spec-artifacts.md)\
21
+ \ when drafting or refining business requirements.\n\n## 1. Triple-Dimension Success\
22
+ \ Metrics\nEvery feature or story must define success across three measurable axes\
23
+ \ to ensure holistic value:\n\n* **Business Metric:** (e.g., \"Increase checkout\
24
+ \ conversion by 5%\" or \"Reduce churn by 2%\").\n* **Performance Target:** (e.g.,\
25
+ \ \"API response SHALL be < 200ms at 95th percentile\").\n* **UX Efficiency:** (e.g.,\
26
+ \ \"The user must complete the KYC flow in < 4 minutes or < 5 screens\").\n\n##\
27
+ \ 2. Key Entities & Domain Integrity\nAvoid \"Anemic Domain Models.\" Define the\
28
+ \ lifecycle and language of the product's core objects.\n\n* **Ubiquitous Language:**\
29
+ \ Entity names (e.g., `Subscription`, `Lead`, `Merchant`) must be identical in the\
30
+ \ UI, the Requirements, and the Database.\n* **State Machine Thinking:** Define\
31
+ \ the **Lifecycle** for complex entities. \n * *Example:* `Draft` ➔ `Pending_Approval`\
32
+ \ ➔ `Active` ➔ `Expired`.\n * Explicitly state prohibited transitions (e.g.,\
33
+ \ \"An `Expired` contract cannot return to `Active`\").\n\n## 3. Golden Rules (Business\
34
+ \ Invariants)\nThese are the \"Laws of the Land\" - immutable logic that governs the\
35
+ \ system regardless of specific UI flows.\n\n* **Logic Constraints:** (e.g., \"\
36
+ A 'Trial' user can never access 'Premium' exports\").\n* **Data Integrity:** (e.g.,\
37
+ \ \"Total order value can never be negative after discounts\").\n* **Safety Guards:**\
38
+ \ (e.g., \"Destructive actions must require a double-confirmation if the entity\
39
+ \ state is `Production`\").\n\n## 4. Acceptance Criteria & Independent Tests\nACs\
40
+ \ must be **binary and testable**. If a machine cannot verify it, the AC is too\
41
+ \ vague.\n\n* **Functional AC:** Specific system behaviors (e.g., \"System sends\
42
+ \ a JWT via the `Authorization` header\").\n* **Negative AC (Edge Cases):** Behavior\
43
+ \ under stress (e.g., \"Return `422 Unprocessable Entity` if the Zip Code does not\
44
+ \ match the State\").\n* **Independent Test (Verification):** Every requirement\
45
+ \ must have a corresponding **Independent Test Case** that can be executed by QA\
46
+ \ or an automated suite without needing the PO's \"interpretation.\"\n\n## 5. Prioritization\
47
+ \ & Scope (The ICE/MoSCoW Hybrid)\n* **ICE Scoring:** Focus on **Impact, Confidence,\
48
+ \ and Ease**. \n* **Aggressive De-scoping:** If an AC doesn't directly support the\
49
+ \ **Success Metric**, move it to the backlog.\n* **Technical Health:** Allocate\
50
+ \ a fixed % (e.g., 20%) of the capacity to resolve Technical Debt and maintain the\
51
+ \ \"Golden Rules.\"\n\n---\n\n## PO Delivery Checklist\n\n- [ ] **Value:** Is the\
52
+ \ \"Problem Statement\" clear and the \"Why\" justified?\n- [ ] **Success Metrics:**\
53
+ \ Are the three dimensions (Business, Perf, UX) defined?\n- [ ] **Key Entities:**\
54
+ \ Is the lifecycle (State Machine) of the entity mapped?\n- [ ] **Golden Rules:**\
55
+ \ Are the immutable business constraints documented?\n- [ ] **Acceptance Criteria:**\
56
+ \ Are they binary? Can a machine verify them?\n- [ ] **Independent Test:** Is there\
57
+ \ a clear test scenario for every \"Happy Path\" and \"Edge Case\"?\n- [ ] **Persona:**\
58
+ \ Is it clear exactly *who* benefits from this change?\n"
@@ -0,0 +1,38 @@
1
+ content: '# Spec Artifacts
2
+
3
+
4
+ Use this reference when shaping discovery outputs or `requirements.md`.
5
+
6
+
7
+ ## Before `requirements.md`
8
+
9
+ - Clarify objective, persona, and business outcome.
10
+
11
+ - Identify constraints from constitution docs.
12
+
13
+ - Reduce idea exploration to the highest-value direction and one fallback.
14
+
15
+
16
+ ## Inside `requirements.md`
17
+
18
+ - Introduction: state the user problem and value in plain language.
19
+
20
+ - Requirements: write each slice as independently testable value.
21
+
22
+ - Key Entities: define business objects and lifecycle language without leaking implementation.
23
+
24
+ - Success Criteria: make outcomes measurable across business, performance, and UX.
25
+
26
+ - UI Contract: if UI exists, define observable expectations rather than vague taste.
27
+
28
+
29
+ ## Clarification Standard
30
+
31
+ - Prefer one ambiguity at a time.
32
+
33
+ - Resolve by updating the requirement text itself with SHALL or MUST language.
34
+
35
+ - Keep a short clarification log, but treat the requirement section as the source
36
+ of truth.
37
+
38
+ '
@@ -0,0 +1,52 @@
1
+ name: spec-clarification-interview
2
+ description: Use when a requirements document has ambiguity or [UNCLEAR] markers and
3
+ needs a one-question-at-a-time clarification interview that updates the source requirement
4
+ incrementally.
5
+ version: 1.0
6
+ priority: HIGH
7
+ content: '# Spec Clarification Interview
8
+
9
+
10
+ > **CORE MANDATE:** Resolve ambiguity directly in the requirement text, one decision
11
+ at a time.
12
+
13
+
14
+ ## When to use this skill
15
+
16
+ Use for clarification loops, ambiguity removal, underspecified business rules, and
17
+ incremental updates to `requirements.md`.
18
+
19
+
20
+ ## How to use it
21
+
22
+ 1. Identify the highest-impact ambiguity first.
23
+
24
+ 2. Ask exactly one question with a recommended option and bounded alternatives.
25
+
26
+ 3. Update the source requirement immediately after the answer.
27
+
28
+
29
+ ## Checklist
30
+
31
+ - [ ] Only one question is asked at a time.
32
+
33
+ - [ ] The recommended option is explicit and justified.
34
+
35
+ - [ ] The source requirement is updated after each answer.
36
+
37
+ - [ ] Clarification history is logged without replacing source-of-truth text.
38
+
39
+ - [ ] No more than 5 questions are asked in one session.
40
+
41
+
42
+ ## Interview Rules
43
+
44
+ - Prioritize lifecycle, security, and error-handling gaps first.
45
+
46
+ - Prefer decision-ready options over open-ended prompts.
47
+
48
+ - Replace `[UNCLEAR]` markers with SHALL or MUST language after the answer.
49
+
50
+ - End with a short coverage summary and the next recommended command.
51
+
52
+ '
@@ -0,0 +1,137 @@
1
+ name: task-atomic-decomposition
2
+ description: Use when converting design into executable tasks. Focuses on 5-20 minute
3
+ task slices, explicit dependencies, verification, rollback, and safe parallel tracks.
4
+ version: 1.0
5
+ priority: HIGH
6
+ content: '# Skill: Task Atomic Decomposition & Dependency Mapping
7
+
8
+
9
+ ## When to use this skill
10
+
11
+ Use when turning design into tasks, splitting large work, sequencing dependencies,
12
+ or defining verify and rollback steps.
13
+
14
+
15
+ ## How to use it
16
+
17
+ 1. Break work into the smallest meaningful units with one clear outcome.
18
+
19
+ 2. Define dependency order, verify command, and rollback per task.
20
+
21
+ 3. Confirm the roadmap can be executed without hidden assumptions.
22
+
23
+
24
+ ## Checklist
25
+
26
+ - [ ] Each task is atomic enough to prove complete quickly.
27
+
28
+ - [ ] Dependencies and parallel tracks are explicit.
29
+
30
+ - [ ] Every task has objective verification and safe rollback.
31
+
32
+
33
+ ## Artifact Guidance
34
+
35
+ - **For `design.md` consumption**: use the class/file inventory and roadmap as the
36
+ raw material for decomposition.
37
+
38
+ - **For `tasks.md`**: produce 5-20 minute slices with verify, rollback, dependency,
39
+ and `[REQ-X]` context.
40
+
41
+ - **For implementation handoff**: ensure every phase ends in a still-working state.
42
+
43
+
44
+ ## References
45
+
46
+ - **Roadmap patterns and decomposition examples**: read [roadmap-patterns.md](references/roadmap-patterns.md)
47
+ when task sizing or rollback quality is unclear.
48
+
49
+
50
+ ## 0. Best Practices (Quick Reference)
51
+
52
+
53
+ | # | Principle | Rule | Why |
54
+
55
+ |---|-----------|------|-----|
56
+
57
+ | 1 | **Task Size** | 5-20 min, one clear outcome | Easy verification & rollback
58
+ |
59
+
60
+ | 2 | **Dependencies** | Explicit blockers only | No hidden failures |
61
+
62
+ | 3 | **Parallel** | Different files/agents OK | Avoid merge conflicts |
63
+
64
+ | 4 | **Verify-First** | Define success before coding | Prevents "done but broken"
65
+ |
66
+
67
+ | 5 | **Rollback** | Every task has recovery path | Tasks fail, prepare for it |
68
+
69
+ | 6 | **Context** | Explain WHY not just WHAT | Better agent decisions |
70
+
71
+ | 7 | **Risks** | Identify before they happen | Prepared responses |
72
+
73
+ | 8 | **Milestones** | Each phase ends with working state | Continuous value |
74
+
75
+ | 9 | **Phase X** | Verification is ALWAYS final | Definition of done |
76
+
77
+
78
+ ## 1. The Micro-Atomic Standard
79
+
80
+ You must break down technical designs into **micro-tasks**. A task is only valid
81
+ if it targets a single logical change that can be verified in isolation.
82
+
83
+ - **Rule of One**: One file, one function, or one configuration entry per task.
84
+
85
+ - **Verify-First**: Every task description must begin with or include the specific
86
+ command or state that confirms success.
87
+
88
+
89
+ ## 2. Dependency & Parallelism Logic
90
+
91
+ - **Explicit Blockers**: Clearly mark tasks that cannot start until another is finished.
92
+
93
+ - **Branching Factor**: Identify tasks that touch different directories or namespaces
94
+ as "Parallel-Ready" to allow multiple agents to work without merge conflicts.
95
+
96
+
97
+ ## 3. The Gravity Rule (Sequencing)
98
+
99
+ Order tasks to build a stable foundation:
100
+
101
+ 1. **Infrastructure/Schema**: The "soil" for the code.
102
+
103
+ 2. **Contracts/Interfaces**: The "promises" between layers.
104
+
105
+ 3. **Core Logic**: The "brain" of the feature.
106
+
107
+ 4. **Implementation/UI**: The "skin" and interaction.
108
+
109
+
110
+ ## 4. Resilience & Rollback
111
+
112
+ For every complex task, the plan must imply or state a recovery path (e.g., "Keep
113
+ a backup of the original config" or "Revert migration on failure"). This ensures
114
+ the system never stays in a corrupted state.
115
+
116
+
117
+ ## 5. Contextual Intelligence
118
+
119
+ Never plan a task as a blind instruction. Every task must carry a fragment of the
120
+ "Why" (referencing `[REQ-X]`) so the Executor understands the business value and
121
+ can make micro-decisions correctly.
122
+
123
+
124
+ ## 6. Decomposition Quality Checklist
125
+
126
+ Before finalizing, verify the roadmap:
127
+
128
+ - [ ] **Atomicity**: Is every task truly a 5-20 minute effort?
129
+
130
+ - [ ] **Verification**: Does every task have a "Success State" defined?
131
+
132
+ - [ ] **Independence**: Can parallel tasks be executed in any order?
133
+
134
+ - [ ] **Working State**: Does every milestone (end of phase) result in a codebase
135
+ that still passes core tests?
136
+
137
+ '
@@ -0,0 +1,103 @@
1
+ content: '# Roadmap Patterns
2
+
3
+
4
+ Use this reference when a design is hard to decompose cleanly.
5
+
6
+
7
+ ## Good Atomic Task Shape
8
+
9
+ - One clear outcome.
10
+
11
+ - One obvious verification path.
12
+
13
+ - One safe rollback path.
14
+
15
+ - Minimal file and dependency surface.
16
+
17
+
18
+ ## Preferred Sequence
19
+
20
+ 1. Infrastructure or schema.
21
+
22
+ 2. Contracts and interfaces.
23
+
24
+ 3. Core logic.
25
+
26
+ 4. Delivery layer or UI.
27
+
28
+ 5. Verification and polish.
29
+
30
+
31
+ ## Scenario Patterns
32
+
33
+
34
+ ### UI-Heavy / Redesign
35
+
36
+ 1. Surface shell or layout boundary.
37
+
38
+ 2. Route/menu/shell integration when the surface introduces a new access path.
39
+
40
+ 3. Surface-specific implementation.
41
+
42
+ 4. UI polish.
43
+
44
+ 5. A11y / responsive verification.
45
+
46
+ 6. Contract verification when backend behavior is consumed.
47
+
48
+
49
+ ### Backend-Heavy / Domain
50
+
51
+ 1. Contract or interface.
52
+
53
+ 2. Domain rule or use case.
54
+
55
+ 3. Persistence / infrastructure.
56
+
57
+ 4. API exposure.
58
+
59
+ 5. Verification.
60
+
61
+
62
+ ### Integration-Heavy
63
+
64
+ 1. External contract assumptions.
65
+
66
+ 2. Adapter or gateway.
67
+
68
+ 3. Failure handling / fallback.
69
+
70
+ 4. Observability.
71
+
72
+ 5. Verification.
73
+
74
+
75
+ ### Migration / Rollout
76
+
77
+ 1. Prepare compatibility.
78
+
79
+ 2. Rollout-compatible implementation.
80
+
81
+ 3. Verification.
82
+
83
+ 4. Cleanup / deprecation removal.
84
+
85
+
86
+ ## Parallelism Rule
87
+
88
+ - Parallelize tasks that touch different files or modules and do not share a hidden
89
+ blocker.
90
+
91
+ - Do not parallelize tasks whose verify steps depend on unfinished upstream contract
92
+ work.
93
+
94
+
95
+ ## Rollback Examples
96
+
97
+ - Restore one config file from the previous content.
98
+
99
+ - Revert one migration file or disable one flag.
100
+
101
+ - Remove one newly introduced route, job, or component.
102
+
103
+ '
@@ -0,0 +1,58 @@
1
+ package agent
2
+
3
+ import (
4
+ "testing"
5
+ )
6
+
7
+ func TestKitManifests(t *testing.T) {
8
+ kitFS, err := GetKitFS()
9
+ if err != nil {
10
+ t.Fatalf("failed to get kit FS: %v", err)
11
+ }
12
+
13
+ registry := &Registry{}
14
+ err = registry.Initialize(kitFS)
15
+ if err != nil {
16
+ t.Fatalf("failed to initialize registry with kit FS: %v", err)
17
+ }
18
+
19
+ // Check open-code
20
+ opencode, ok := registry.GetAgent("open-code")
21
+ if !ok {
22
+ t.Error("expected to find 'open-code' agent in kit")
23
+ } else {
24
+ if opencode.DirName != ".opencode/" {
25
+ t.Errorf("expected open-code DirName '.opencode/', got '%s'", opencode.DirName)
26
+ }
27
+ }
28
+
29
+ // Check kilo-code
30
+ kilocode, ok := registry.GetAgent("kilo-code")
31
+ if !ok {
32
+ t.Error("expected to find 'kilo-code' agent in kit")
33
+ } else {
34
+ if kilocode.DirName != ".kilocode/" {
35
+ t.Errorf("expected kilo-code DirName '.kilocode/', got '%s'", kilocode.DirName)
36
+ }
37
+ }
38
+
39
+ // Check antigravity (to be sure)
40
+ antigravity, ok := registry.GetAgent("antigravity")
41
+ if !ok {
42
+ t.Error("expected to find 'antigravity' agent in kit")
43
+ } else {
44
+ if antigravity.DirName != ".agent/" {
45
+ t.Errorf("expected antigravity DirName '.agent/', got '%s'", antigravity.DirName)
46
+ }
47
+ }
48
+
49
+ // Check kimi-code
50
+ kimicode, ok := registry.GetAgent("kimi-code")
51
+ if !ok {
52
+ t.Error("expected to find 'kimi-code' agent in kit")
53
+ } else {
54
+ if kimicode.DirName != ".kimi/" {
55
+ t.Errorf("expected kimi-code DirName '.kimi/', got '%s'", kimicode.DirName)
56
+ }
57
+ }
58
+ }
@@ -0,0 +1,15 @@
1
+ package agent
2
+
3
+ // AgentMetadata contains the descriptive metadata for an agent.
4
+ type AgentMetadata struct {
5
+ ID string `yaml:"id"`
6
+ Name string `yaml:"name"`
7
+ Description string `yaml:"description"`
8
+ DirName string `yaml:"dir_name"`
9
+ Version string `yaml:"version"`
10
+ }
11
+
12
+ // AgentManifest is the structure of the manifest.yaml file found in each agent directory.
13
+ type AgentManifest struct {
14
+ AgentMetadata `yaml:",inline"`
15
+ }
@@ -0,0 +1,69 @@
1
+ package agent
2
+
3
+ import (
4
+ "fmt"
5
+ "io/fs"
6
+ "sort"
7
+
8
+ "github.com/jeancodogno/specforce-kit/src/internal/core"
9
+ "gopkg.in/yaml.v3"
10
+ )
11
+
12
+ // Registry stores and manages discovered agent metadata.
13
+ type Registry struct {
14
+ agents map[string]AgentMetadata
15
+ }
16
+
17
+ // Initialize parses kit.yaml from the provided filesystem to populate agent metadata.
18
+ func (r *Registry) Initialize(kitFS fs.FS) error {
19
+ r.agents = make(map[string]AgentMetadata)
20
+
21
+ data, err := fs.ReadFile(kitFS, "kit.yaml")
22
+ if err != nil {
23
+ return fmt.Errorf("failed to read kit.yaml: %w", err)
24
+ }
25
+
26
+ var config core.KitConfig
27
+ if err := yaml.Unmarshal(data, &config); err != nil {
28
+ return fmt.Errorf("failed to parse kit.yaml: %w", err)
29
+ }
30
+
31
+ for id, route := range config.Tools {
32
+ name := route.Name
33
+ if name == "" {
34
+ name = id
35
+ }
36
+
37
+ metadata := AgentMetadata{
38
+ ID: id,
39
+ Name: name,
40
+ Description: route.Description,
41
+ DirName: route.Target,
42
+ Version: "1.0.0", // default since we removed version
43
+ }
44
+
45
+ r.agents[id] = metadata
46
+ }
47
+
48
+ return nil
49
+ }
50
+
51
+ // GetAgents returns a list of all discovered agent metadata, sorted by ID.
52
+ func (r *Registry) GetAgents() []AgentMetadata {
53
+ agents := make([]AgentMetadata, 0, len(r.agents))
54
+ for _, a := range r.agents {
55
+ agents = append(agents, a)
56
+ }
57
+
58
+ sort.Slice(agents, func(i, j int) bool {
59
+ return agents[i].ID < agents[j].ID
60
+ })
61
+
62
+ return agents
63
+ }
64
+
65
+ // GetAgent returns a specific agent's metadata by ID.
66
+ func (r *Registry) GetAgent(id string) (AgentMetadata, bool) {
67
+ a, ok := r.agents[id]
68
+ return a, ok
69
+ }
@@ -0,0 +1,51 @@
1
+ package agent
2
+
3
+ import (
4
+ "testing"
5
+ "testing/fstest"
6
+ )
7
+
8
+ func TestRegistry_Initialize(t *testing.T) {
9
+ mockFS := fstest.MapFS{
10
+ "kit.yaml": {
11
+ Data: []byte(`
12
+ tools:
13
+ claude:
14
+ name: "Claude"
15
+ description: "Claude agent"
16
+ target: ".claude"
17
+ gemini:
18
+ name: "Gemini"
19
+ description: "Gemini agent"
20
+ target: ".gemini"
21
+ `),
22
+ },
23
+ "some-other-file.txt": {
24
+ Data: []byte("ignored"),
25
+ },
26
+ }
27
+
28
+ registry := &Registry{}
29
+ err := registry.Initialize(mockFS)
30
+ if err != nil {
31
+ t.Fatalf("failed to initialize registry: %v", err)
32
+ }
33
+
34
+ agents := registry.GetAgents()
35
+ if len(agents) != 2 {
36
+ t.Errorf("expected 2 agents, got %d", len(agents))
37
+ }
38
+
39
+ claude, ok := registry.GetAgent("claude")
40
+ if !ok {
41
+ t.Error("expected to find 'claude' agent")
42
+ }
43
+ if claude.Name != "Claude" {
44
+ t.Errorf("expected Name 'Claude', got '%s'", claude.Name)
45
+ }
46
+
47
+ _, ok = registry.GetAgent("non-existent")
48
+ if ok {
49
+ t.Error("did not expect to find 'non-existent' agent")
50
+ }
51
+ }