sdg-agents 1.0.5

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/02-problem-definition.md

@@ -0,0 +1,63 @@
+# 02 - Problem Definition
+
+## The Current Problem
+
+- What is broken or inefficient today?
+- What is the primary pain point for the user or the business?
+
+## Risks and Compliance
+
+- Are there sensitive data (LGPD/GDPR)?
+- What are the security risks (leakage, unauthorized access)?
+- Are there any legal or industry compliance requirements?
+
+## Why solve it now?
+
+- What is the cost of not solving this problem?
+- What opportunities are we missing?
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 02 - Problem Definition
+
+## The Current Problem
+
+The system is slow and users are complaining about constant crashes.
+
+## Risks and Compliance
+
+We haven't identified any risks yet.
+
+## Why solve it now?
+
+So that users don't get angry.
+```
+
+> **Rationale**: Ignores security and compliance risks, treating them as "non-existent" due to lack of analysis.
+
+### ✅ Good Example
+
+```markdown
+# 02 - Problem Definition
+
+## The Current Problem
+
+The cash closing process takes 40 minutes daily in 80% of stores, causing frustration and financial errors.
+
+## Risks and Compliance
+
+- **Data**: Tax ID (CPF) and purchase data of 1M customers (LGPD).
+- **Risk**: Payment gateway API keys exposed in the code.
+- **Compliance**: PCI-DSS audit required for the new flow.
+
+## Why solve it now?
+
+The annual operational cost is $2.5M. Additionally, an LGPD fine for a data leak could exceed $50M.
+```
+
+> **Rationale**: Defines clear security risks, legally protected data, and financial impacts of compliance.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/03-success-metrics.md

@@ -0,0 +1,48 @@
+# 03 - Success Metrics
+
+## KPIs (Indicators)
+
+- Which metric will be moved (e.g., response time, conversion rate)?
+- What is the current baseline and what is the target?
+
+## Success Checklist
+
+- [ ] Feature X running in production.
+- [ ] Automated tests with 80%+ coverage.
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 03 - Success Metrics
+
+## KPIs
+
+The system must be very fast and easy to use.
+
+## Success Checklist
+
+- [ ] Everything ready.
+```
+
+> **Rationale**: How do you test "easy"? Without numbers, success is a subjective opinion.
+
+### ✅ Good Example
+
+```markdown
+# 03 - Success Metrics
+
+## KPIs
+
+Increase the checkout completion rate from 65% to 90% in the first 3 months after launch.
+
+## Success Checklist
+
+- [x] Response < 500ms P95 across all APIs.
+- [x] 100% of business flows covered by integration tests.
+```
+
+> **Rationale**: Provides a target number (90%), a baseline value (65%), a timeframe (3 months), and clear technical criteria.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/05-engineering-culture-and-silos.md

@@ -0,0 +1,41 @@
+# 05 - Engineering Culture & Code Hostage (Anti-Silos)
+
+Knowledge silos destroy the productivity and scalability of a technical team. "Hero Culture" _(Single Point of Failure / Bus Factor = 1)_ — where only one developer knows how to handle the payment system or the deployment — is an unacceptable operational risk at the Staff Engineering level.
+
+## Code Ownership Principles
+
+- The code belongs to the organization, not to the person who wrote it. No one is the absolute "owner" of a service.
+- The code must be written in such a way that a newly hired Mid-level Developer can understand and maintain it without having to call the original author in the middle of the night.
+
+## Practical Anti-Code-Hostage Measures
+
+- **Mandatory Code Review:** No one pushes code directly to the `Main` branch (exception for regulated _hotfixes_). Mandatory `Approve` from at least 1 developer who was NOT the author of the task.
+- **Domain Rotation (Pairing):** If the Squad is going to do a major refactoring of module X, the Senior Dev who masters the subject MUST pair (Pair Programming) with another developer, focusing on knowledge dilution.
+- **Systemic Permissions:** Master access to the Production Database or the AWS Deployment key is never in the hands of one and only one person. Systemic "Hostage-taking" is not allowed. (Use Vaults or IAM Roles).
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# Culture
+
+- Pedro handles the Sales table because he knows it. We don't even touch it.
+- If the database freezes, call him on his cell in the middle of the night.
+```
+
+> **Rationale**: Chronic Hero Culture. The project stops running during Pedro's vacation or becomes a hostage if he leaves the company. Furthermore, Pedro himself becomes overwhelmed (technical burnout).
+
+### ✅ Good Example
+
+```markdown
+# Technical Culture and Continuity
+
+- Every new API related to `Billing` must have mandatory pairing of 1 Senior Dev + 1 Mid-level Dev.
+- **Bus Factor Check:** At the end of each quarter (Quarter), the Tech Lead ensures that at least 3 devs from the Chapter are comfortable performing a Manual Deploy of the Critical module in Production.
+- CI/CD automatically blocks _Pull Requests_ of any `.config` file if the reviewer is not from another squad (Cross-review to avoid configuration silos).
+```
+
+> **Rationale**: We transform the "goodwill" to teach into a Management Metric (Quarterly Bus Factor) and an automatic technical restriction in the CI/CD. No one takes the codebase hostage, and the team sleeps in peace.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/06-foundation-approval.md

@@ -0,0 +1,57 @@
+# 06 - Foundation Approval
+
+## Artifacts Checklist
+
+- [ ] 01-project-vision.md (Complete)
+- [ ] 02-problem-definition.md (Complete)
+- [ ] 03-success-metrics.md (Complete)
+- [ ] 05-engineering-culture-and-silos.md (Complete)
+
+## Stakeholder Approval
+
+- **Project Manager**: [Signature/Date]
+- **Lead Architect**: [Signature/Date]
+
+## Definition of Readiness (Ready for Setup)
+
+- [ ] Budget approved for the first 3 months.
+- [ ] Core team allocated.
+- [ ] Stakeholders agree on success metrics.
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 04 - Approval: Foundation
+
+## Artifacts Checklist
+
+- [x] Filled.
+
+## Definition of Readiness
+
+- [x] Everything ok.
+```
+
+> **Rationale**: Checkboxes filled without evidence or names of responsible parties.
+
+### ✅ Good Example
+
+```markdown
+# 06 - Approval: Foundation
+
+## Stakeholder Approval
+
+- **Manager**: John Doe (Approved on 2026-05-10)
+- **Architect**: Jane Smith (Approved on 2026-05-12)
+
+## Definition of Readiness
+
+- [x] AWS budget of $5k/month approved by the board.
+- [x] Project vision reflects the real problem of the stores.
+```
+
+> **Rationale**: Real names, dates, and confirmation of concrete facts (Budget approval).

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/01-tech-stack.md

@@ -0,0 +1,62 @@
+# 01 - Tech Stack
+
+## Chosen Technologies
+
+- **Language**: [e.g., Go, TS, C#]
+- **Framework**: [e.g., FastAPI, React, Gin]
+- **Database**: [e.g., PostgreSQL, Redis]
+
+## Choice Rationale
+
+- Why did we choose these technologies over others?
+- What are the pros and cons?
+
+## Version Management (LTS) and Dependencies
+
+- Are the chosen frameworks and runtimes Long Term Support (LTS) versions?
+- What is the strategy for continuous updates and vulnerability mitigation (e.g., Dependabot, Renovate)?
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 01 - Tech Stack
+
+## Chosen Technologies
+
+Python and MySQL.
+
+## Choice Rationale
+
+Because it's what the team knows how to use and it's popular.
+
+## Version Management (LTS)
+
+We'll use the newest version or whatever works.
+```
+
+> **Rationale**: Popularity does not justify critical architecture decisions. Where is the trade-off?
+
+### ✅ Good Example
+
+```markdown
+# 01 - Tech Stack
+
+## Chosen Technologies
+
+Go 1.21, PostgreSQL 15, Redis 7.
+
+## Choice Rationale
+
+Go was chosen for its concurrency performance (Goroutines) required for processing 5k RPS, and PostgreSQL for ACID consistency in critical financial transactions.
+
+## Version Management (LTS)
+
+- **Runtimes**: Only even versions of Node.js (e.g., v20) and Go in its supported versions.
+- **Automated Updates**: Dependabot configured via `.github/dependabot.yml` for weekly automatic patch updates.
+```
+
+> **Rationale**: Justifies the choice based on non-functional requirements (concurrency and consistency).

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/02-local-environment.md

@@ -0,0 +1,50 @@
+# 02 - Local Environment
+
+## Prerequisites
+
+- What does the developer need to have installed (e.g., Docker, Taskfile, Make)?
+- Minimum version of the tools.
+
+## How to Run
+
+1.  [ ] Clone the repo.
+2.  [ ] Install dependencies.
+3.  [ ] Start the containers.
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 02 - Local Environment
+
+## Prerequisites
+
+Docker and Python.
+
+## How to Run
+
+Run docker-compose up.
+```
+
+> **Rationale**: What if Docker Compose fails? Where are the necessary environment variables (.env)?
+
+### ✅ Good Example
+
+```markdown
+# 02 - Local Environment
+
+## Prerequisites
+
+Docker 24+, Python 3.11, Make 4.3+.
+
+## How to Run
+
+1. Copy .env.example to .env.
+2. Run `make setup` to download images and run migrations.
+3. Test access at `localhost:8080/health`.
+```
+
+> **Rationale**: Provides minimum versions, clear initial configuration steps (.env), and a final verification test.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/03-version-control-and-tracking.md

@@ -0,0 +1,65 @@
+# 03 - Version Control and Management
+
+## Branch Strategy (Versioning)
+
+- What standard flow will be adopted (GitHub Flow, GitFlow, Trunk-Based)?
+- What are the naming rules for creating new branches?
+
+## Commit Standard
+
+- Will the project adopt _Conventional Commits_?
+- Will there be passive protection (**Developer review**) or active protection (Husky/Commitlint before push)?
+
+## Traceability and Task Management
+
+- What is the official tracking tool (Jira, Linear, Azure DevOps)?
+- How does the PR (Pull Request) link to the business task described in the specification?
+- What is the status transition rule for cards when the code is merged?
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 03 - Version Control and Management
+
+## Branch Strategy
+
+We'll use basic Git. Create a branch with the functionality and then throw it into master.
+
+## Commit Standard
+
+Write something understandable, e.g., "uploading login screen fixes" and "wip".
+
+## Traceability
+
+When the task is finished, notify management on Slack and move the Trello card to Done.
+```
+
+> **Rationale**: Total lack of governance and traceability. In a short time, the repository will have severe integration conflicts, impossibility of generating automatic _Changelogs_, and management will not know which code in production belongs to which specification.
+
+### ✅ Good Example
+
+```markdown
+# 03 - Version Control and Management
+
+## Branch Strategy (Versioning)
+
+- **Flow**: GitHub Flow (Simplified Trunk-Based).
+- **Naming**: Mandatory to follow the pattern and the spec ID (e.g., `feat/AUTH-102-implement-oauth`, `fix/AUTH-105-token-timeout`).
+
+## Commit Standard
+
+- **Standard**: Strict compliance with _Conventional Commits_ (`feat:`, `fix:`, `chore:`, `refactor:`).
+- **Guarantee**: Use of `Husky` + `Commitlint` blocking non-standard commits via _pre-commit_.
+
+## Traceability and Task Management
+
+- **Tracking**: Linear (Issue Tracker).
+- **Linking**: Every PR must contain the tracking ID in the title (e.g., "[AUTH-102] Implement OAuth via Google").
+- **Workflow**: GitHub integration with Linear moves tickets to `In Review` when the PR is opened and to `Done` upon _Merge_.
+```
+
+> **Rationale**: Creates a perfect audit trail (_End-to-End_). Every line of code changed is linked to a business decision and PR approval. Furthermore, semantic releases can be published 100% automatically by the CI/CD based on _Conventional Commits_.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/04-hello-world-validation.md

@@ -0,0 +1,37 @@
+# 04 - Hello World Validation
+
+## What Was Validated?
+
+- [ ] The app is running.
+- [ ] The first endpoint has been exposed.
+- [ ] The first test is passing.
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 04 - Hello World Validation
+
+## What Was Validated?
+
+Everything is fine, the app started locally.
+```
+
+> **Rationale**: How do you prove success? Where is the healthcheck log?
+
+### ✅ Good Example
+
+```markdown
+# 04 - Hello World Validation
+
+## What Was Validated?
+
+- [x] 200 OK response on the `/health` endpoint.
+- [x] Startup log displays "Server listening on port 8080".
+- [x] The `npm test` command successfully executed the first basic test.
+```
+
+> **Rationale**: Provides concrete and traceable evidence of successful initialization.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/05-setup-approval.md

@@ -0,0 +1,61 @@
+# 05 - Setup Approval
+
+## Artifacts Checklist
+
+- [ ] 01-tech-stack.md (Complete)
+- [ ] 02-local-environment.md (Complete)
+- [ ] 03-version-control-and-tracking.md (Defined)
+- [ ] 04-hello-world-validation.md (Passed)
+
+## Technical Approval
+
+- **Lead Developer**: [Signature/Date]
+- **QA Engineer**: [Signature/Date]
+
+## Definition of Readiness (Ready for Architecture)
+
+- [ ] Local environment running in less than 10 minutes.
+- [ ] Base pipeline is configured (Hello World in Staging).
+- [ ] Team agrees with the Chosen Stack.
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 05 - Setup Approval
+
+## Checklist
+
+- [x] Tech Stack done (Python).
+
+## Definition of Readiness
+
+- [x] The app runs.
+```
+
+> **Rationale**: How do you prove that the app "runs"? Where is the Hello World log? And the version control strategy?
+
+### ✅ Good Example
+
+```markdown
+# 05 - Setup Approval
+
+## Checklist
+
+- [x] 01-tech-stack.md (Approved: Go 1.21 + Redis)
+- [x] 03-version-control-and-tracking.md (Approved: GitHub Flow + Linear)
+- [x] 04-hello-world-validation.md (Passed: Healthcheck 200 OK)
+
+## Technical Approval
+
+- **Leader**: Robert Snow (2026-05-15)
+
+## Definition of Readiness
+
+- [x] `make setup` ran without errors on 3 different machines.
+```
+
+> **Rationale**: Technical details and multi-machine validation (overcoming "it works on my machine").

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/01-folder-structure.md

@@ -0,0 +1,49 @@
+# 01 - Folder Structure
+
+## Repository Layout
+
+- Why organize it this way?
+- Where does everything go?
+
+## Main Folders
+
+- `/cmd`: Entrypoints.
+- `/internal`: Private application code.
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 01 - Folder Structure
+
+## Repository Layout
+
+Let's put everything in the root to make it easier to find.
+
+## Main Folders
+
+- `/src`: All code goes here.
+```
+
+> **Rationale**: "Everything in the root" fails miserably in projects that scale. A generic `/src` doesn't separate responsibilities.
+
+### ✅ Good Example
+
+```markdown
+# 01 - Folder Structure
+
+## Repository Layout
+
+We've adopted the `Standard Go Project Layout` to separate entrypoints from internal logic.
+
+## Main Folders
+
+- `/cmd`: Application binaries.
+- `/internal/domain`: Entities and business logic.
+- `/internal/infra`: DB implementation and API clients.
+```
+
+> **Rationale**: Follows industry standards (Go Standard Layout) and explicitly separates domain from infrastructure.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/02-design-patterns.md

@@ -0,0 +1,59 @@
+# 02 - Architectural Styles and Design Patterns
+
+## Architectural Style (Macro)
+
+- **Chosen Approach**: [e.g., Modular Monolith, Microservices, Serverless]
+- **Justification**: Why did we choose this approach? If microservices, why not start with a modular monolith?
+
+## Code Design Patterns (Micro)
+
+- **Software Architecture**: [e.g., Clean Arch, Hexagonal, Vertical Slices]
+- **Domain Modeling**: [e.g., DDD, Rich Domain Models, Result Pattern]
+
+## Implementation Patterns
+
+- **Flow Control and Errors**: How do we handle errors? (e.g., `Envelope Pattern`, `if err != nil`)
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 02 - Architectural Styles and Design Patterns
+
+## Architectural Style (Macro)
+
+We will use microservices to scale better in the future.
+
+## Chosen Patterns
+
+We will use programming best practices.
+
+## Implementation Patterns
+
+The code will be clean and commented.
+```
+
+> **Rationale**: Justifying "microservices" based on future scale is speculative (Premature Optimization). "Best practices" and "clean" are vague and subjective.
+
+### ✅ Good Example
+
+```markdown
+# 02 - Architectural Styles and Design Patterns
+
+## Architectural Style (Macro)
+
+**Modular Monolith**. We will start bundled to reduce network costs and DevOps complexity, separating contexts via strict internal packages.
+
+## Chosen Patterns
+
+Hexagonal Architecture with Vertical Slices for modules. Business logic via Result Pattern.
+
+## Implementation Patterns
+
+Errors will be handled via the Envelope Pattern (Result<T>), avoiding pure exceptions for business flow control.
+```
+
+> **Rationale**: Explicitly addresses the macro trade-off (Modular Monolith vs Microservices) and defines specific, testable code choices.

package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/03-apis-and-communication.md

@@ -0,0 +1,55 @@
+# 03 - Integrations, APIs, and Communication
+
+## Contracts and Interfaces (Synchronous)
+
+- **External APIs**: [e.g., REST for Web, GraphQL for Mobile/Complex UIs]
+- **Internal Communication (Service-to-Service)**: [e.g., gRPC via Protobuf, isolated REST calls]
+
+## Entry Gates and Routing
+
+- **API Gateways / BFF**: [e.g., AWS API Gateway for Rate Limiting and Central Auth, BFF for aggregating mobile payload]
+
+## Asynchronous and Event-Driven
+
+- **Message Brokers**: [e.g., RabbitMQ, AWS SQS, Apache Kafka]
+- **Asynchronous Use Cases**: Which flows shouldn't block the user's main request? (e.g., sending emails, processing payments). Detail the _Publishers_ and _Subscribers_.
+
+---
+
+## Learn by Examples
+
+### ❌ Bad Example
+
+```markdown
+# 03 - Integrations, APIs, and Communication
+
+## Contracts and Interfaces (Synchronous)
+
+Our API will be REST and services will talk via HTTP.
+
+## Asynchronous and Event-Driven
+
+We will use RabbitMQ for heavy background tasks.
+```
+
+> **Rationale**: It doesn't specify why temporal failures in HTTP are acceptable for internal services, nor details the technological reasoning for RabbitMQ. It completely ignores Gateway layer concepts.
+
+### ✅ Good Example
+
+```markdown
+# 03 - Integrations, APIs, and Communication
+
+## Contracts and Interfaces (Synchronous)
+
+Public exposure via **GraphQL** (using BFF for mobile payload limitation). Internal Service-to-Service communication via **gRPC** ensuring strong typing and low latency.
+
+## Entry Gates and Routing
+
+All external traffic passes through an **API Gateway** responsible for TLS termination, Rate Limiting, and JWT token validation (Auth offloading).
+
+## Asynchronous and Event-Driven
+
+The checkout finalization string will emit an "OrderCreated" event via **RabbitMQ**. The Notification service will act as a subscriber to dispatch emails without blocking the user's HTTP response (temporal decoupling).
+```
+
+> **Rationale**: Defines objective protocol choices based on client profile (GraphQL vs gRPC), protects the core domain using API Gateways, and applies Event-Driven Architecture (EDA) for secondary background flows.