@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.
- package/.geminiignore +15 -0
- package/.github/workflows/ci.yml +100 -0
- package/.github/workflows/release.yml +51 -0
- package/.golangci.yml +21 -0
- package/.goreleaser.yaml +43 -0
- package/.rgignore +13 -0
- package/.specforce/config.yaml +32 -0
- package/.specforce/docs/.gitkeep +0 -0
- package/.specforce/docs/architecture.md +98 -0
- package/.specforce/docs/engineering.md +80 -0
- package/.specforce/docs/governance.md +30 -0
- package/.specforce/docs/memorial.md +44 -0
- package/.specforce/docs/principles.md +31 -0
- package/.specforce/docs/security.md +31 -0
- package/.specforce/docs/ui-ux.md +129 -0
- package/.specforce/specs/.gitkeep +0 -0
- package/AGENTS.md +36 -0
- package/CONTRIBUTING.md +81 -0
- package/LICENSE +21 -0
- package/Makefile +49 -0
- package/README.md +144 -0
- package/assets/logo-header.png +0 -0
- package/assets/logo.png +0 -0
- package/docs/artifacts.md +41 -0
- package/docs/cli.md +73 -0
- package/docs/configuration.md +50 -0
- package/docs/getting-started.md +110 -0
- package/docs/supported-tools.md +14 -0
- package/go.mod +35 -0
- package/go.sum +61 -0
- package/index.js +0 -0
- package/package.json +26 -0
- package/src/cmd/specforce/main.go +23 -0
- package/src/cmd/specforce/main_test.go +7 -0
- package/src/internal/agent/artifacts/constitution/architecture.yaml +70 -0
- package/src/internal/agent/artifacts/constitution/engineering.yaml +52 -0
- package/src/internal/agent/artifacts/constitution/governance.yaml +41 -0
- package/src/internal/agent/artifacts/constitution/memorial.yaml +55 -0
- package/src/internal/agent/artifacts/constitution/principles.yaml +54 -0
- package/src/internal/agent/artifacts/constitution/security.yaml +47 -0
- package/src/internal/agent/artifacts/constitution/ui-ux.yaml +158 -0
- package/src/internal/agent/artifacts/spec/design.yaml +50 -0
- package/src/internal/agent/artifacts/spec/requirements.yaml +48 -0
- package/src/internal/agent/artifacts/spec/tasks.yaml +55 -0
- package/src/internal/agent/compatibility_test.go +120 -0
- package/src/internal/agent/cwd_test.go +9 -0
- package/src/internal/agent/embed.go +19 -0
- package/src/internal/agent/integration_test.go +138 -0
- package/src/internal/agent/kit/agents/product-analyst.yaml +31 -0
- package/src/internal/agent/kit/agents/technical-developer.yaml +28 -0
- package/src/internal/agent/kit/agents/technical-project-planner.yaml +30 -0
- package/src/internal/agent/kit/agents/technical-qa-engineer.yaml +36 -0
- package/src/internal/agent/kit/agents/technical-solution-architect.yaml +32 -0
- package/src/internal/agent/kit/commands/archive.yaml +25 -0
- package/src/internal/agent/kit/commands/constitution.yaml +132 -0
- package/src/internal/agent/kit/commands/implement.yaml +96 -0
- package/src/internal/agent/kit/commands/spec.yaml +94 -0
- package/src/internal/agent/kit/instructions/archive.md +68 -0
- package/src/internal/agent/kit/kit.yaml +111 -0
- package/src/internal/agent/kit/skills/opportunity-framing/SKILL.yaml +56 -0
- package/src/internal/agent/kit/skills/pragmatic-product-owner/SKILL.yaml +58 -0
- package/src/internal/agent/kit/skills/pragmatic-product-owner/references/spec-artifacts.yaml +38 -0
- package/src/internal/agent/kit/skills/spec-clarification-interview/SKILL.yaml +52 -0
- package/src/internal/agent/kit/skills/task-atomic-decomposition/SKILL.yaml +137 -0
- package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml +103 -0
- package/src/internal/agent/kit_manifests_test.go +58 -0
- package/src/internal/agent/manifest.go +15 -0
- package/src/internal/agent/registry.go +69 -0
- package/src/internal/agent/registry_test.go +51 -0
- package/src/internal/agent/translator.go +334 -0
- package/src/internal/agent/translator_test.go +734 -0
- package/src/internal/cli/archive.go +91 -0
- package/src/internal/cli/archive_test.go +67 -0
- package/src/internal/cli/cli.go +259 -0
- package/src/internal/cli/cli_test.go +130 -0
- package/src/internal/cli/cobra/archive.go +26 -0
- package/src/internal/cli/cobra/console.go +21 -0
- package/src/internal/cli/cobra/constitution.go +44 -0
- package/src/internal/cli/cobra/dummy_test.go +7 -0
- package/src/internal/cli/cobra/implementation.go +50 -0
- package/src/internal/cli/cobra/init.go +23 -0
- package/src/internal/cli/cobra/install.go +21 -0
- package/src/internal/cli/cobra/root.go +47 -0
- package/src/internal/cli/cobra/spec.go +91 -0
- package/src/internal/cli/console.go +48 -0
- package/src/internal/cli/constitution.go +190 -0
- package/src/internal/cli/constitution_test.go +50 -0
- package/src/internal/cli/implementation.go +153 -0
- package/src/internal/cli/implementation_test.go +165 -0
- package/src/internal/cli/spec.go +369 -0
- package/src/internal/cli/spec_test.go +85 -0
- package/src/internal/constitution/registry.go +139 -0
- package/src/internal/constitution/registry_test.go +97 -0
- package/src/internal/constitution/status.go +70 -0
- package/src/internal/constitution/status_test.go +160 -0
- package/src/internal/core/blueprint.go +49 -0
- package/src/internal/core/blueprint_test.go +58 -0
- package/src/internal/core/config.go +124 -0
- package/src/internal/core/config_test.go +145 -0
- package/src/internal/core/constants.go +13 -0
- package/src/internal/core/errors.go +31 -0
- package/src/internal/core/errors_test.go +48 -0
- package/src/internal/core/hooks.go +89 -0
- package/src/internal/core/hooks_test.go +51 -0
- package/src/internal/core/kit.go +15 -0
- package/src/internal/core/kit_test.go +65 -0
- package/src/internal/core/path.go +115 -0
- package/src/internal/core/path_test.go +101 -0
- package/src/internal/core/ui.go +19 -0
- package/src/internal/installer/dependencies.go +23 -0
- package/src/internal/installer/install.go +89 -0
- package/src/internal/installer/installer.go +45 -0
- package/src/internal/installer/installer_test.go +96 -0
- package/src/internal/project/agents_md.go +108 -0
- package/src/internal/project/agents_md_test.go +101 -0
- package/src/internal/project/bootstrapper.go +64 -0
- package/src/internal/project/bootstrapper_test.go +89 -0
- package/src/internal/project/detector.go +35 -0
- package/src/internal/project/detector_test.go +96 -0
- package/src/internal/project/refresh_integration_test.go +86 -0
- package/src/internal/project/service.go +93 -0
- package/src/internal/project/service_test.go +135 -0
- package/src/internal/spec/archive.go +49 -0
- package/src/internal/spec/archive_test.go +55 -0
- package/src/internal/spec/discovery.go +53 -0
- package/src/internal/spec/discovery_test.go +60 -0
- package/src/internal/spec/implementation.go +296 -0
- package/src/internal/spec/implementation_test.go +253 -0
- package/src/internal/spec/registry.go +142 -0
- package/src/internal/spec/registry_test.go +105 -0
- package/src/internal/spec/scanner.go +219 -0
- package/src/internal/spec/scanner_test.go +243 -0
- package/src/internal/spec/service.go +157 -0
- package/src/internal/spec/service_test.go +238 -0
- package/src/internal/spec/status.go +94 -0
- package/src/internal/spec/status_test.go +146 -0
- package/src/internal/spec/tasks.go +103 -0
- package/src/internal/spec/tasks_test.go +137 -0
- package/src/internal/tui/components.go +132 -0
- package/src/internal/tui/console.go +247 -0
- package/src/internal/tui/console_test.go +19 -0
- package/src/internal/tui/constitution.go +36 -0
- package/src/internal/tui/constitution_test.go +32 -0
- package/src/internal/tui/implementation.go +151 -0
- package/src/internal/tui/logo.go +89 -0
- package/src/internal/tui/multiselect.go +199 -0
- package/src/internal/tui/progressbar.go +37 -0
- package/src/internal/tui/progressbar_test.go +30 -0
- package/src/internal/tui/spec.go +35 -0
- package/src/internal/tui/spinner.go +66 -0
- package/src/internal/tui/terminal.go +18 -0
- package/src/internal/tui/theme.go +125 -0
- 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
|
+
'
|
package/src/internal/agent/kit/skills/task-atomic-decomposition/references/roadmap-patterns.yaml
ADDED
|
@@ -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
|
+
}
|