sdg-agents 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/LICENSE +15 -0
  2. package/README.md +161 -0
  3. package/package.json +88 -0
  4. package/src/assets/dev-guides/agent-deep-flow.md +139 -0
  5. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/01-project-scope-and-mvp.md +45 -0
  6. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/02-stack-and-data-model.md +56 -0
  7. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/03-external-integrations.md +44 -0
  8. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/04-launch-checklist.md +26 -0
  9. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/01-project-vision.md +77 -0
  10. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/02-problem-definition.md +63 -0
  11. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/03-success-metrics.md +48 -0
  12. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/05-engineering-culture-and-silos.md +41 -0
  13. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/06-foundation-approval.md +57 -0
  14. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/01-tech-stack.md +62 -0
  15. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/02-local-environment.md +50 -0
  16. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/03-version-control-and-tracking.md +65 -0
  17. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/04-hello-world-validation.md +37 -0
  18. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/05-setup-approval.md +61 -0
  19. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/01-folder-structure.md +49 -0
  20. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/02-design-patterns.md +59 -0
  21. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/03-apis-and-communication.md +55 -0
  22. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/04-security-and-access.md +63 -0
  23. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/05-security-audit.md +64 -0
  24. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/06-design-system-ux.md +72 -0
  25. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/07-ai-strategy.md +72 -0
  26. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/08-observability.md +65 -0
  27. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/09-technical-documentation.md +64 -0
  28. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/10-infrastructure-and-costs.md +40 -0
  29. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/11-data-privacy-compliance.md +41 -0
  30. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/12-performance-and-scale.md +46 -0
  31. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/13-disaster-recovery.md +39 -0
  32. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/14-architecture-approval.md +81 -0
  33. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/03-delivery/01-ci-cd-pipeline.md +49 -0
  34. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/03-delivery/02-quality-standards.md +46 -0
  35. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/03-delivery/03-delivery-approval.md +58 -0
  36. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/00-feature-template.md +30 -0
  37. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/01-context-and-scope.md +46 -0
  38. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/02-business-rules.md +39 -0
  39. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/03-architecture-and-design.md +50 -0
  40. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/04-testing-strategy.md +48 -0
  41. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/05-implementation-plan.md +45 -0
  42. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/06-feature-approval.md +46 -0
  43. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/05-evolution/01-rfcs-and-changes.md +63 -0
  44. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/05-evolution/02-incident-postmortems.md +64 -0
  45. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/05-evolution/03-adr-template.md +66 -0
  46. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/00-foundation/01-legacy-vision.md +73 -0
  47. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/00-foundation/02-foundation-approval.md +53 -0
  48. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/01-tech-debt-inventory.md +55 -0
  49. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/02-security-audit.md +63 -0
  50. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/03-regression-baseline.md +49 -0
  51. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/04-analysis-approval.md +65 -0
  52. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/01-modernization-approach.md +60 -0
  53. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/02-versioning-and-coexistence.md +57 -0
  54. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/03-new-demands-triage.md +41 -0
  55. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/04-strategy-approval.md +56 -0
  56. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/03-refactor/01-cleanup-backlog.md +45 -0
  57. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/03-refactor/02-refactor-approval.md +53 -0
  58. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/04-migration/01-migration-roadmap.md +47 -0
  59. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/04-migration/02-data-sync-strategy.md +56 -0
  60. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/04-migration/03-migration-approval.md +55 -0
  61. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/05-sunset/01-decommission-plan.md +47 -0
  62. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/05-sunset/02-sunset-approval.md +60 -0
  63. package/src/assets/dev-guides/prompt-tracks/README.md +144 -0
  64. package/src/assets/dev-guides/software-development-lifecycle-sdlc.md +147 -0
  65. package/src/assets/dev-guides/spec-driven-dev-guide.md +81 -0
  66. package/src/assets/dev-guides/ui-prompt-guide.md +181 -0
  67. package/src/assets/img/sdg-agents-icon-dark.svg +55 -0
  68. package/src/assets/img/sdg-agents-icon-light.svg +55 -0
  69. package/src/assets/img/sdg-agents-menu-v1.png +0 -0
  70. package/src/assets/img/sdg-icon.svg +110 -0
  71. package/src/assets/instructions/commands/sdg-docs.md +69 -0
  72. package/src/assets/instructions/commands/sdg-feat.md +45 -0
  73. package/src/assets/instructions/commands/sdg-fix.md +41 -0
  74. package/src/assets/instructions/commands/sdg-land.md +128 -0
  75. package/src/assets/instructions/competencies/backend.md +353 -0
  76. package/src/assets/instructions/competencies/frontend.md +439 -0
  77. package/src/assets/instructions/core/agent-roles.md +104 -0
  78. package/src/assets/instructions/core/api-design.md +65 -0
  79. package/src/assets/instructions/core/ci-cd.md +144 -0
  80. package/src/assets/instructions/core/cloud.md +63 -0
  81. package/src/assets/instructions/core/code-style.md +144 -0
  82. package/src/assets/instructions/core/containers.md +115 -0
  83. package/src/assets/instructions/core/data-access.md +119 -0
  84. package/src/assets/instructions/core/engineering-standards.md +502 -0
  85. package/src/assets/instructions/core/naming.md +136 -0
  86. package/src/assets/instructions/core/observability.md +73 -0
  87. package/src/assets/instructions/core/security-pipeline.md +209 -0
  88. package/src/assets/instructions/core/security.md +45 -0
  89. package/src/assets/instructions/core/sql-style.md +138 -0
  90. package/src/assets/instructions/core/staff-dna.md +72 -0
  91. package/src/assets/instructions/core/testing-principles.md +212 -0
  92. package/src/assets/instructions/core/ui/architecture.md +171 -0
  93. package/src/assets/instructions/core/ui/design-thinking.md +319 -0
  94. package/src/assets/instructions/core/ui/presets.md +200 -0
  95. package/src/assets/instructions/core/ui/standards.md +144 -0
  96. package/src/assets/instructions/core/writing-soul.md +82 -0
  97. package/src/assets/instructions/flavors/legacy/principles.md +64 -0
  98. package/src/assets/instructions/flavors/lite/principles.md +39 -0
  99. package/src/assets/instructions/flavors/mvc/principles.md +124 -0
  100. package/src/assets/instructions/flavors/vertical-slice/principles.md +178 -0
  101. package/src/assets/instructions/idioms/csharp/patterns.md +367 -0
  102. package/src/assets/instructions/idioms/flutter/patterns.md +97 -0
  103. package/src/assets/instructions/idioms/go/patterns.md +193 -0
  104. package/src/assets/instructions/idioms/java/patterns.md +233 -0
  105. package/src/assets/instructions/idioms/javascript/patterns.md +223 -0
  106. package/src/assets/instructions/idioms/kotlin/patterns.md +94 -0
  107. package/src/assets/instructions/idioms/python/patterns.md +185 -0
  108. package/src/assets/instructions/idioms/rust/patterns.md +189 -0
  109. package/src/assets/instructions/idioms/scripts/patterns.md +81 -0
  110. package/src/assets/instructions/idioms/sql/patterns.md +109 -0
  111. package/src/assets/instructions/idioms/swift/patterns.md +97 -0
  112. package/src/assets/instructions/idioms/typescript/patterns.md +304 -0
  113. package/src/assets/instructions/idioms/vbnet/patterns.md +96 -0
  114. package/src/assets/instructions/idioms/vbnet-legacy/patterns.md +104 -0
  115. package/src/assets/instructions/templates/workflow.md +244 -0
  116. package/src/assets/instructions/workflows/governance.md +162 -0
  117. package/src/engine/bin/add-idiom.mjs +186 -0
  118. package/src/engine/bin/index.mjs +226 -0
  119. package/src/engine/config/stack-display.mjs +75 -0
  120. package/src/engine/config/stack-versions.mjs +76 -0
  121. package/src/engine/lib/cli-parser.mjs +80 -0
  122. package/src/engine/lib/display-utils.mjs +20 -0
  123. package/src/engine/lib/fs-utils.mjs +99 -0
  124. package/src/engine/lib/instruction-assembler.mjs +487 -0
  125. package/src/engine/lib/manifest-utils.mjs +128 -0
  126. package/src/engine/lib/prompt-utils.mjs +137 -0
  127. package/src/engine/lib/result-utils.mjs +14 -0
  128. package/src/engine/lib/ruleset-injector.mjs +183 -0
  129. package/src/engine/lib/ui-utils.mjs +216 -0
  130. package/src/engine/lib/wizard.mjs +472 -0
@@ -0,0 +1,49 @@
1
+ # 01 - CI/CD Pipeline
2
+
3
+ ## Deploy Flow
4
+
5
+ - What are the pipeline steps? (e.g., `LINT -> TEST -> BUILD -> DEPLOY`)
6
+ - What tool do we use? (e.g., GitHub Actions, GitLab CI)
7
+
8
+ ## Approval Requirements (PR)
9
+
10
+ - [ ] Linter without errors.
11
+ - [ ] Tests passing.
12
+
13
+ ---
14
+
15
+ ## Learn by Examples
16
+
17
+ ### ❌ Bad Example
18
+
19
+ ```markdown
20
+ # 01 - CI/CD Pipeline
21
+
22
+ ## Deploy Flow
23
+
24
+ Git Push and Docker.
25
+
26
+ ## Approval Requirements
27
+
28
+ Whoever the creator wants.
29
+ ```
30
+
31
+ > **Rationale**: "Git Push" is not a pipeline. "Whoever the creator wants" invalidates technical governance.
32
+
33
+ ### ✅ Good Example
34
+
35
+ ```markdown
36
+ # 01 - CI/CD Pipeline
37
+
38
+ ## Deploy Flow
39
+
40
+ GitHub Actions: `LINT` -> `UNIT-TEST` -> `SAST` -> `DOCKER-BUILD` -> `AWS-DEPLOY`.
41
+
42
+ ## Approval Requirements
43
+
44
+ - [x] Linter passing.
45
+ - [x] 100% of unit tests green.
46
+ - [x] 0 critical vulnerabilities in SonarQube.
47
+ ```
48
+
49
+ > **Rationale**: Defines technologies (GitHub Actions, SonarQube), clear steps, and rigid requirements for the PR.
@@ -0,0 +1,46 @@
1
+ # 02 - Quality Standards
2
+
3
+ ## What Does Quality Mean to Us?
4
+
5
+ - Code without obvious technical debt.
6
+ - Tests that actually test business rules.
7
+
8
+ ## Minimum Coverage
9
+
10
+ - [e.g., 80% in business logic]
11
+
12
+ ---
13
+
14
+ ## Learn by Examples
15
+
16
+ ### ❌ Bad Example
17
+
18
+ ```markdown
19
+ # 02 - Quality Standards
20
+
21
+ ## What is Quality
22
+
23
+ Having few bugs and pretty code.
24
+
25
+ ## Minimum Coverage
26
+
27
+ 10%.
28
+ ```
29
+
30
+ > **Rationale**: "Few bugs" and "pretty" are subjective. 10% coverage is insignificant and dangerous.
31
+
32
+ ### ✅ Good Example
33
+
34
+ ```markdown
35
+ # 02 - Quality Standards
36
+
37
+ ## What is Quality
38
+
39
+ Code that follows SOLID principles and 100% of critical payment flows with E2E test coverage.
40
+
41
+ ## Minimum Coverage
42
+
43
+ 80% line coverage in `/internal/domain`.
44
+ ```
45
+
46
+ > **Rationale**: Defines concrete principles (SOLID) and aggressive testing goals for critical areas.
@@ -0,0 +1,58 @@
1
+ # 03 - Delivery Approval
2
+
3
+ ## Artifacts Checklist
4
+
5
+ - [ ] 01-ci-cd-pipeline.md (Running)
6
+ - [ ] 02-quality-standards.md (Approved)
7
+
8
+ ## Operational Approval
9
+
10
+ - **SRE / DevOps**: [Signature/Date]
11
+ - **Tech Lead**: [Signature/Date]
12
+
13
+ ## Definition of Readiness (Ready for Features)
14
+
15
+ - [ ] Automated CI/CD pipeline up to Staging.
16
+ - [ ] Linter and Unit Tests block PRs.
17
+ - [ ] Basic monitoring (Logs/Metrics) active.
18
+
19
+ ---
20
+
21
+ ## Learn by Examples
22
+
23
+ ### ❌ Bad Example
24
+
25
+ ```markdown
26
+ # 03 - Delivery Approval
27
+
28
+ ## Checklist
29
+
30
+ - [x] The pipeline works.
31
+
32
+ ## Definition of Readiness
33
+
34
+ - [x] Ready to code.
35
+ ```
36
+
37
+ > **Rationale**: "Works" is vague. Where is the automatic Staging deploy log?
38
+
39
+ ### ✅ Good Example
40
+
41
+ ```markdown
42
+ # 03 - Delivery Approval
43
+
44
+ ## Checklist
45
+
46
+ - [x] 01-ci-cd-pipeline.md (GitHub Actions Active)
47
+
48
+ ## Operational Approval
49
+
50
+ - **SRE / DevOps**: Lana Lime (2026-05-30)
51
+
52
+ ## Definition of Readiness
53
+
54
+ - [x] PR blocking configured in GitHub for Lint/Test failures.
55
+ - [x] Grafana "Health" Dashboard created in Staging.
56
+ ```
57
+
58
+ > **Rationale**: Defines real operational criteria such as PR blocking and active monitoring.
@@ -0,0 +1,30 @@
1
+ # [ID]- [Feature Name]
2
+
3
+ ## Context
4
+
5
+ - Problem to be solved.
6
+ - Expected business or system impact.
7
+
8
+ ## Scope
9
+
10
+ - Planned deliverables.
11
+ - What will NOT be covered (Non-goals).
12
+
13
+ ## Business Rules
14
+
15
+ - Critical validations.
16
+ - Success and exception flowcharts.
17
+
18
+ ## Architecture & Design
19
+
20
+ - Integration point with the current system.
21
+ - Definition of new contracts (API) or schema changes (DB).
22
+
23
+ ## Implementation Roadmap
24
+
25
+ 1. [ ] Task 1
26
+ 2. [ ] Task 2
27
+
28
+ ## Testing Strategy
29
+
30
+ - Validation scenarios (A, B, C).
@@ -0,0 +1,46 @@
1
+ # 01 - Context and Scope (Context & Scope)
2
+
3
+ ## Problem and Impact (What and Why)
4
+
5
+ - **Business Problem:** Which customer or operational "pain point" are we solving?
6
+ - **Affected Metrics:** What do we expect to improve? (e.g., +Conversion, -Response Time, +Retention).
7
+ - **Target Audience:** Does it affect all users, admins, or just a specific role?
8
+
9
+ ## Scope (Scope Boundaries)
10
+
11
+ - **In-Scope (Goals):** What **MUST** be delivered as part of this feature.
12
+ - **Out-of-Scope (Non-Goals):** What we **WILL NOT** do now (fundamental to protect against _Scope Creep_).
13
+
14
+ ---
15
+
16
+ ## Learn by Examples
17
+
18
+ ### ❌ Bad Example
19
+
20
+ ```markdown
21
+ # Context
22
+
23
+ We need to add an export to PDF button.
24
+
25
+ # Scope
26
+
27
+ Make the export work.
28
+ ```
29
+
30
+ > **Rationale**: Does not say "Why". Exporting to PDF is the solution, not the problem. What if the problem is "the accountant needs the monthly report"? Perhaps a CSV silently sent by email would be better than a slow button on the UI.
31
+
32
+ ### ✅ Good Example
33
+
34
+ ```markdown
35
+ # Context
36
+
37
+ **Problem:** Currently, our shopkeepers spend 4 hours a month taking screenshots of sales screens to send to accounting.
38
+ **Metrics:** Reduce time spent by shopkeepers (CSAT) and decrease CS tickets asking for reports.
39
+
40
+ # Scope
41
+
42
+ **In-Scope:** UI-based export of CSV and PDF reports from the "Financial" tab.
43
+ **Out-of-Scope:** Automatic scheduling (Cron) of report delivery. We will only perform manual exports for now.
44
+ ```
45
+
46
+ > **Rationale**: Defines the root problem and blocks inappropriate future proposals for the moment (such as automatic scheduling) that would delay delivery.
@@ -0,0 +1,39 @@
1
+ # 02 - Business Rules
2
+
3
+ ## Logic and Behavior
4
+
5
+ - **Main Flow (Happy Path):** What is the ideal path for the entity or user? (Use Clear User Stories or Flowcharts).
6
+ - **Domain Constraints:** Logical limits of the application. (e.g., "An order cannot move from 'Shipped' back to 'Pending'").
7
+
8
+ ## Edge Cases & Validations (Sad Path)
9
+
10
+ - **Edge Scenarios:** What happens when parameters are invalid? (e.g., "Age < 18 on a blocked purchase").
11
+ - **Concurrency (Race Conditions):** What if 2 users access the same resource simultaneously? (e.g., buying the last ticket).
12
+ - **Partial Resilience:** If something external fails, do we block everything or offer a fallback?
13
+
14
+ ---
15
+
16
+ ## Learn by Examples
17
+
18
+ ### ❌ Bad Example
19
+
20
+ ```markdown
21
+ # Rules
22
+
23
+ - The user submits the form and it's saved in the 'tbl_users' database.
24
+ - If it fails, return 500.
25
+ ```
26
+
27
+ > **Rationale**: It's coupled to the database and technical errors (500). Business rules should be described in a technology-agnostic way, focusing on _behavior_ rather than _implementation_.
28
+
29
+ ### ✅ Good Example
30
+
31
+ ```markdown
32
+ # Rules
33
+
34
+ - **Happy Path:** The shopkeeper creates a Coupon and defines its validity. The system allows its use on listed products.
35
+ - **Constraints:** The coupon discount value can never be greater than the price of the lowest-priced item in the cart (To avoid negative order balances).
36
+ - **Concurrency (Race Condition):** A coupon with `use_limit = 1` must use Optimistic Locking; if two users attempt checkout in the same millisecond, one will receive a "Coupon Exhausted" error.
37
+ ```
38
+
39
+ > **Rationale**: The developer will read this and IMMEDIATELY remember to shield the entity against "negative values" and apply a database lock when debiting the coupon.
@@ -0,0 +1,50 @@
1
+ # 03 - Architecture and Technical Design (Architecture & Design)
2
+
3
+ ## API-First (Contracts and Envelopes)
4
+
5
+ - **Exposed Endpoints:** Routes, Verbs (GET/POST/PUT/PATCH/DELETE), or gRPC methods.
6
+ - **Request Payload:** Expected input format.
7
+ - **Response Schemas (Envelopes):** The unified success format and, crucially, the unified standard for **Business Error** or Validation messages.
8
+
9
+ ## Data Modeling (Data Models / Persistence)
10
+
11
+ - **Entities and Relationships:** Which tables/collections should be created/altered? (ER Diagram or Mermaid).
12
+ - **Migration Strategy:** Will we need to migrate data from legacy or just insert columns (Add-only)? What about indexes for read queries?
13
+
14
+ ## External Integrations (Third-parties)
15
+
16
+ - **Suppliers/Vendors:** Does the feature call AWS S3, Stripe, Slack, etc.?
17
+ - **Rate Limits & Fallback:** How does the feature handle the failure of this third-party API?
18
+
19
+ ---
20
+
21
+ ## Learn by Examples
22
+
23
+ ### ❌ Bad Example
24
+
25
+ ```markdown
26
+ # API and DB
27
+
28
+ Create a POST /upload route.
29
+ Save the PDF in the Docs table.
30
+ ```
31
+
32
+ > **Rationale**: Vague and subject to free interpretation (every Dev will do it differently). It doesn't show possible HTTP statuses or where the actual large binaries will live.
33
+
34
+ ### ✅ Good Example
35
+
36
+ ```markdown
37
+ # Contracts (API-First)
38
+
39
+ - **POST** `/api/v1/workspaces/{id}/reports`
40
+ - **Expected HTTP Statuses:** `201 Created` (Success), `422 Unprocessable` (Validation), `404 Not Found` (Non-existent Workspace).
41
+ - **Response Envelope:** The `422` error must follow [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) (Problem Details).
42
+
43
+ # Data Modeling
44
+
45
+ - **Relational Table:** `reports (id, type, target_month, status, file_url)`.
46
+ - **Constraint:** `UNIQUE (workspace_id, target_month)` to avoid duplicate report generation.
47
+ - **Storage:** The physical file (.pdf) will be streamed directly to an S3 Bucket (Never store Blobs in a relational database).
48
+ ```
49
+
50
+ > **Rationale**: Puts an end to endless PR discussions. The Front-End Dev knows exactly what payload to expect (even if the backend hasn't coded anything yet). The DBA understands the indexes that will be generated.
@@ -0,0 +1,48 @@
1
+ # 04 - Testing Strategy (Testing Strategy)
2
+
3
+ ## TDD / BDD Approach
4
+
5
+ - Which key behaviors described in the `02-business-rules.md` file must be covered by **Unit Tests**? (e.g., Testing the exception thrown when weight is negative).
6
+ - Which routes described in the `03-architecture-and-design.md` file will require **Integration Tests** simulating real requests using Mocks/Stubs for the Database/External Dependencies?
7
+
8
+ ## Extreme Cases (Smoke & Performance)
9
+
10
+ - Does the feature involve heavy data? Will a load testing script (K6, JMeter) be necessary?
11
+ - How to validate if integrations with third-party applications fail gracefully (e.g., banking API timeout)?
12
+
13
+ ---
14
+
15
+ ## Learn by Examples
16
+
17
+ ### ❌ Bad Example
18
+
19
+ ```markdown
20
+ # Strategy
21
+
22
+ Create tests with Jest/XUnit.
23
+ Run in the CI.
24
+ ```
25
+
26
+ > **Rationale**: Too generic. Every squad will run tests in the CI, but WHAT needs to be tested so that we can validate even before the first "If" is programmed?
27
+
28
+ ### ✅ Good Example
29
+
30
+ ```markdown
31
+ # Testing Strategy
32
+
33
+ **Unit (Unit Tests - Domain Focus)**
34
+ Should focus on the `CouponDomain` Entity:
35
+
36
+ - `(Happy Path)` If valid, discounts value.
37
+ - `(Sad Path)` Throws `InsufficientBalanceException`.
38
+ - `(Sad Path)` Throws `ExpiredCouponException` if CurrentDate > Validity.
39
+
40
+ **Integration (Controller/API Focus)**
41
+
42
+ - Mock external payment API to always return "Approved".
43
+ - Execute POST /checkout request and ensure that:
44
+ - The `tbl_orders` table inserted a new ID.
45
+ - Final return `201 Created` and body contains `{ success: true, order_id: 12 }`.
46
+ ```
47
+
48
+ > **Rationale**: Based on this _Strategy_, even more junior devs build efficient `.spec.ts` files without being afraid of the PR being blocked or leaving security holes or domain failures.
@@ -0,0 +1,45 @@
1
+ # 05 - Implementation Plan (Implementation Plan)
2
+
3
+ ## Execution Checklist
4
+
5
+ - **Dependent Stages:** Which steps must necessarily come before another? (e.g., Database Migrations **before** Use Cases, and Use Cases **before** HTTP/gRPC APIs).
6
+ - **Parallelized Deliveries:** Can the frontend be executed in parallel based on the `03-architecture` document (API-First contracts)? Which Jira IDs and tasks accompany it?
7
+
8
+ ## Rollout, Fallback & Observability
9
+
10
+ - How are we going to launch in production? In percentages (Canary Config) or via **Feature Flags** (Dark Launch)?
11
+ - **Fallback Plan:** How to undo this instantly without downtime? And which logs (Datadog/ELK) will trigger the alert if the 500 Error level spikes?
12
+
13
+ ---
14
+
15
+ ## Learn by Examples
16
+
17
+ ### ❌ Bad Example
18
+
19
+ ```markdown
20
+ # Execution
21
+
22
+ 1. Do database, 2. Do Backend, 3. Do Frontend, 4. Deploy Friday.
23
+ ```
24
+
25
+ > **Rationale**: Trivial and lacks managerial visibility or structured tactics. Besides being incredibly susceptible to "Merge conflicts" in a large team, it generates panic if an error occurs (no Rollback!).
26
+
27
+ ### ✅ Good Example
28
+
29
+ ```markdown
30
+ # Checklist (Implementation Stages)
31
+
32
+ - `[FRONT]` Issue #212: Mock base form based on the `/api/v2/products` contract.
33
+ - `[BACK]` Issue #213: Create PR with `Flyway Migration` `.sql`: adding the "tags" table (Add-only).
34
+ - `[BACK]` Issue #214: Implement DB interface repositories.
35
+ - `[BACK]` Issue #215: Connect Controller to UseCases.
36
+ - `[INTEGRATION]`: Connect UI to already existing endpoints in Staging.
37
+
38
+ # Operational Strategy
39
+
40
+ - All endpoints and new UI components will be protected behind the Feature Flag `FEATURE_ENABLE_PRODUCT_TAGS=false`.
41
+ - We will enable only for _Internal Users_ (Admins).
42
+ - We will increase to 25% of the base. If Datadog points to a P95 latency error > 1s, the dashboard itself inverts the Flag (Automatic Instant Fallback). No need for a new Deploy to rollback the code.
43
+ ```
44
+
45
+ > **Rationale**: Brings extreme confidence in CD (Continuous Delivery). The million-dollar feature is "live" in the code, but selectively enabled and with 1-second Fallbacks.
@@ -0,0 +1,46 @@
1
+ # 06 - Readiness (Feature Approval Check)
2
+
3
+ ## Definition of Done (DoD)
4
+
5
+ - This artifact should act as the final release Gatekeeper before the PR (Pull Request) goes to Master/Main.
6
+ - Revisit the 5 previous template files before "signing off" on the delivery of this Feature.
7
+
8
+ ## Sign-offs (Mutual Approval)
9
+
10
+ - **Product Manager**: [Signature/Date]
11
+ - **Tech Lead**: [Signature/Date]
12
+
13
+ ---
14
+
15
+ ## Learn by Examples
16
+
17
+ ### ❌ Bad Example
18
+
19
+ ```markdown
20
+ # Approval
21
+
22
+ - Tests run on Master. Everything is ok.
23
+ - Someone looked at the PR and gave LGTM.
24
+ ```
25
+
26
+ > **Rationale**: Passive and loose validation. The process needs checklists that enforce the technical QA of the architecture that the **Spec-Driven Kit** imposed.
27
+
28
+ ### ✅ Good Example
29
+
30
+ ```markdown
31
+ # Feature Gatekeeper / Checklist
32
+
33
+ - [x] Context and Scope (Is Document `01` clear and in-scope respected)?
34
+ - [x] All User Stories mapped in Doc `02` are in the E2E/Unit Tests?
35
+ - [x] Was the API-First Contract and Model/Migrations (Doc `03`) strictly followed? (If any route changes occurred, were dependent teams informed?)
36
+ - [x] Are all exception cases from Document `04` Asserted in the CI Pipeline?
37
+ - [x] Rollback / Feature-Flags implemented according to Doc `05`? No hardcoded connections?
38
+
39
+ # Sign-offs / Hand-offs
40
+
41
+ - **Product Owner:** PM reviewed final interface in `Staging` (Julia Silver - 2026-04-21).
42
+ - **Tech Lead:** Code Security review and SonarQube green without critical `Code Smells` (Robert Coast - 2026-04-22).
43
+ - **Status:** APPROVED. 🚀 Ready to enable the flag on the `Main` branch.
44
+ ```
45
+
46
+ > **Rationale**: Ensures organizational discipline; all submitted code faithfully reflects the initial feature planning. The team understands dependencies and ties together Testing, Rollback, and Behavior threads from end to end.
@@ -0,0 +1,63 @@
1
+ # 01 - Request for Comments (RFC) & Architecture Changes
2
+
3
+ ## Problem and Motivation for Change
4
+
5
+ - What motivated the evolution of this architecture in an already live system (e.g., performance bottleneck in the relational database forcing the use of NoSQL, or a Cloud Provider change)?
6
+ - What is the impact of _Doing Nothing_ (Status Quo) compared to the effort of the change?
7
+
8
+ ## Alternatives Considered
9
+
10
+ - What were "Paths B and C" that the team rejected before proposing "Path A"?
11
+ - Why is the chosen option the most suitable today (Cost x Return)?
12
+
13
+ ## Execution and Rollback Plan
14
+
15
+ - How will the current code base be migrated to the new foundation without _Downtime_?
16
+ - What is the acceptable error threshold to abort the change and revert to the previous state?
17
+
18
+ ---
19
+
20
+ ## Learn by Examples
21
+
22
+ ### ❌ Bad Example
23
+
24
+ ```markdown
25
+ # 01 - RFC: Change Database
26
+
27
+ ## Motivation
28
+
29
+ MongoDB is slow.
30
+
31
+ ## Alternatives
32
+
33
+ PostgreSQL is better.
34
+
35
+ ## Execution
36
+
37
+ We'll do a script on Saturday.
38
+ ```
39
+
40
+ > **Rationale**: RFC with zero scientific basis. It disregards that there is no "silver bullet" and attempts to inflict a radical change on the structure without analyzing the cost of data migration and _downtime_.
41
+
42
+ ### ✅ Good Example
43
+
44
+ ```markdown
45
+ # 01 - RFC: Decouple Notification Module to Messaging (RabbitMQ)
46
+
47
+ ## Motivation
48
+
49
+ **Problem**: Current synchronous Email requests via API cause _Timeouts_ (5s) during peak hours (Black Friday), freezing Main App threads.
50
+
51
+ ## Alternatives Considered
52
+
53
+ 1. **Pay for larger instances (Scale Up)**: Rejected for not being financially scalable in the long term.
54
+ 2. **AWS SQS (Serverless)**: Rejected because the budget is locked and we already have an idle bare-metal server in the infra.
55
+ 3. **RabbitMQ (Chosen)**: Ensures asynchronicity with zero license cost.
56
+
57
+ ## Execution
58
+
59
+ - **Shadow**: In the 1st week, RabbitMQ will be enabled but will publish invisible logs while the synchronous code remains active, just to check data consistency.
60
+ - **Rollback**: If `AckRate < 99.9%`, we flip the `UseAsyncNotifications` _Feature Flag_ to `false` in the remote dashboard in real-time, without the need for a _Deploy_.
61
+ ```
62
+
63
+ > **Rationale**: Mature approach, evaluating financial costs and ensuring that the plan does not cause panic for product managers by having real-time security _Feature Flags_.
@@ -0,0 +1,64 @@
1
+ # 02 - Incident Post-Mortems (Outage Analysis)
2
+
3
+ ## Timeline and Impact
4
+
5
+ - What was the exact timeline from the start of the systemic failure to full recovery (_Time to Recovery_)?
6
+ - How many users or transactions were impacted by the downtime? Were there alerts covering this specific type of failure?
7
+
8
+ ## Root Cause Analysis ("The 5 Whys")
9
+
10
+ - How did the system break? (Avoid pointing fingers at individuals _"Someone messed up"_; focus on the process _"The pipeline let it through"_).
11
+ - What was the "hidden trigger" that didn't appear in the _Staging / Homogenization_ environment?
12
+
13
+ ## Action Plan (Action Items)
14
+
15
+ - What does the team **need to implement** in the code, infrastructure, or CI/CD so that this failure **never** happens again structurally in the future?
16
+
17
+ ---
18
+
19
+ ## Learn by Examples
20
+
21
+ ### ❌ Bad Example
22
+
23
+ ```markdown
24
+ # 02 - Post-Mortem: Database Down
25
+
26
+ ## Impact
27
+
28
+ It was bad in the afternoon, and customers complained.
29
+
30
+ ## Root Cause
31
+
32
+ John ran the wrong migration command in production.
33
+
34
+ ## Action Items
35
+
36
+ John will be more careful and take a SQL course.
37
+ ```
38
+
39
+ > **Rationale**: Classic blame culture. Condemning the developer does not resolve systemic fragility. In 6 months, "Joseph" will run the wrong command again because the pipeline remains loose.
40
+
41
+ ### ✅ Good Example
42
+
43
+ ```markdown
44
+ # 02 - Post-Mortem: Master Database Down (DB-Outage)
45
+
46
+ ## Timeline
47
+
48
+ - `14:02 PM`: PostgreSQL CPU usage hits 100%.
49
+ - `14:05 PM`: Gateway starts returning Status 504 in the App for ~4,500 connected users.
50
+ - `14:14 PM`: Datadog alarm goes off in the Ops Slack. Escalation triggered.
51
+ - `14:26 PM`: Manual rollback of the _Target Group_, restored to normality. Duration of **24 min**.
52
+
53
+ ## Root Cause Analysis
54
+
55
+ 1. **Why did the CPU explode?** N+1 query from a heavy report uploaded this morning.
56
+ 2. **Why did it pass the CI?** Lack of data volume metrics in the _Load Test_ pipeline.
57
+
58
+ ## Action Items
59
+
60
+ - **[Tomorrow]**: Add a mandatory global pagination limit `limit(50)` in the Base API.
61
+ - **[By Friday]**: Integrate `k6` into the CI with a cloned database at 10% volume, blocking any query `> 500ms`.
62
+ ```
63
+
64
+ > **Rationale**: Professionalized the failure. Without a witch hunt, the failure becomes the genetic seed of automated protection in the company's future infrastructure.
@@ -0,0 +1,66 @@
1
+ # 03 - Architecture Decision Record (ADR)
2
+
3
+ This standard template must be used to document any and all structuring architectural decisions throughout the project's life. An ADR ensures that the historical context of the decision (Why didn't we use tool X?) will be preserved forever.
4
+
5
+ ## Context and Problem
6
+
7
+ - **Status:** [Proposed | Accepted | Rejected | Obsolete]
8
+ - **What is the current technical pain?** What motivated the team to seek a new architectural solution or insert a new heavy dependency?
9
+
10
+ ## Options Considered
11
+
12
+ - Option 1: [Name and Brief Description] (Pros and Cons)
13
+ - Option 2: [Name and Brief Description] (Pros and Cons)
14
+
15
+ ## Decision (What we will do)
16
+
17
+ - Option X was chosen because [Rationale].
18
+
19
+ ## Consequences and Trade-offs
20
+
21
+ - What do we lose with this decision? (e.g., +Cost, steeper learning curve).
22
+ - What do we gain? (e.g., +Scalability, -Latency).
23
+
24
+ ---
25
+
26
+ ## Learn by Examples
27
+
28
+ ### ❌ Bad Example
29
+
30
+ ```markdown
31
+ # ADR: Migrate to Postgres
32
+
33
+ **Status:** Done
34
+ We chose PostgreSQL because MySQL was slow and the CTO ordered it. We will gain speed.
35
+ ```
36
+
37
+ > **Rationale**: Lacks metrics. "Was slow" is not a metric. What were the evaluated trade-offs? Which versions of PG vs. MySQL operated under stress? Anyone who inherits this in the future will not know the _real_ weight of the technical decision.
38
+
39
+ ### ✅ Good Example
40
+
41
+ ```markdown
42
+ # ADR: Migrate RabbitMQ Queue to AWS SQS
43
+
44
+ **Status:** Accepted
45
+
46
+ ## Context
47
+
48
+ We have 1M jobs/day and the on-premise RabbitMQ cluster managed by us consumes 20h/month of DevOps just in patches and OOM (Out-of-memory) monitoring.
49
+
50
+ ## Options Considered
51
+
52
+ - 1. **Paid RabbitMQ Cloud**: Cost $500/month. Preserves our existing code.
53
+ - 2. **AWS SQS**: Estimated cost $8/month thanks to low throughput; requires rewriting the backend's IMessageQueue interface.
54
+
55
+ ## Decision
56
+
57
+ Option 2 (SQS) was chosen due to unbeatable long-term cost margins and being fully serverless.
58
+
59
+ ## Consequences
60
+
61
+ - Gains: Zero hours in infrastructure maintenance, cost reduced from $500 to $8.
62
+ - Losses: Estimated 1-sprint refactor (~12 points) in the Backend to switch libraries.
63
+ - Risk: Partial lock-in to the AWS cloud.
64
+ ```
65
+
66
+ > **Rationale**: Perfect history. Someone 3 years in the future reads this document and perfectly understands the cost and operational pressures of the time. No one will debate and reignite the desire to return to RabbitMQ without a more solid argument.