@juancr11/sibu 0.1.0

package/templates/skills/architecture/command-pattern/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: command-pattern
+description: Use this skill to design and implement software features as independent, end-to-end Vertical Slices using the Command Pattern, Hexagonal Architecture, and DDD principles.
+---
+
+# Skill: Command-Oriented Vertical Slice Architect
+
+## Description
+Use this skill to design and implement software features as independent, end-to-end Vertical Slices. This approach combines the Command Pattern with Hexagonal Architecture and DDD principles. It ensures that business logic is decoupled from transport layers (CLI, API) and infrastructure (Databases, Third-party SDKs).
+
+---
+
+## 1. The Component Contract
+Every feature is defined by four distinct roles. This separation ensures that the "Core" logic remains pure and testable.
+
+| Component | Responsibility | Constraints |
+| :--- | :--- | :--- |
+| **Command** | Represents Intent | A flat, immutable data structure. No logic, no dependencies. |
+| **Handler** | Represents Execution | The orchestrator. Receives one Command, coordinates with Ports, and returns a Result. |
+| **Port** | Represents Requirement | An interface defined inside the feature folder describing what the handler needs (e.g., SaveUserPort). |
+| **Adapter** | Represents Implementation | The low-level code (SQL, HTTP Client) that satisfies a Port. |
+
+---
+
+## 2. Directory Structure (The "Vertical Slice" Blueprint)
+Organize by Capability (what the system does) rather than Technical Layer (what the code is). This minimizes "shotgun surgery" and increases cohesion.
+
+```text
+/src
+  ├── /entrypoints          # Driving Adapters (The "Edges")
+  │    └── /cli             # Parses flags/args -> creates Command -> calls Handler
+  ├── /features             # THE HEXAGON (Domain & Application Logic)
+  │    └── /feature-name    # e.g., "archive-project"
+  │         ├── command     # The Input DTO
+  │         ├── handler     # The Orchestration logic
+  │         ├── ports       # Interfaces required by the handler
+  │         └── result      # The Output DTO/Contract
+  ├── /shared               # Universal logic only
+  │    ├── /domain          # Global Entities (e.g., "User", "Project")
+  │    └── /errors          # Global error definitions
+  └── /infrastructure       # Driven Adapters (Implementation Details)
+       ├── /persistence     # DB implementations of feature Ports
+       └── /clients         # External API implementations of feature Ports
+```
+
+---
+
+## 3. Operational Rules for Implementation
+
+### Rule 1: Feature Isolation
+A feature folder must never import from another feature folder. If two features need the same logic, that logic must be promoted to the /shared directory.
+
+### Rule 2: Dependency Inversion
+The Handler must never instantiate a database, a file system, or a network client. It must receive its dependencies (via Ports) through its constructor or initialization.
+
+### Rule 3: Transport Agnosticism
+The Handler must be "blind" to the entrypoint. It should not know if it is being triggered by a CLI terminal, a Cron job, or a REST API. It returns domain results, never transport-specific codes (e.g., no HTTP 404s or CLI exit codes).
+
+### Rule 4: Thin Entrypoints
+Entrypoints (CLI/API) are responsible for Syntactic Validation (is the input the right type?). Handlers are responsible for Semantic Validation (does this operation make sense in the current state of the system?).
+
+---
+
+## 4. Implementation Workflow
+1. Define the Command: Identify the minimum data needed to represent the user's intent.
+2. Define the Ports: Identify what external systems the handler needs to talk to. Define these as interfaces in the feature folder.
+3. Implement the Handler: Write the coordination logic. Fetch entities, apply business rules, and use Ports to persist changes.
+4. Wire the Adapter: Implement the concrete infrastructure code in the /infrastructure layer.
+5. Connect the Entrypoint: In the CLI layer, map raw input to the Command and trigger the Handler.
+
+---
+
+## 5. Constraint Checklist for Agent Reviews
+- [ ] Zero Leakage: Does the Handler contain CLI-specific code (like fmt.Printf or flags)?
+- [ ] Interface-Driven: Does the Handler depend on a concrete Database class or an Interface (Port)?
+- [ ] Folder Integrity: Does the feature folder contain the Command, Handler, and Ports?
+- [ ] Dependency Direction: Does the infrastructure layer depend on the feature ports, and not the other way around?

package/templates/skills/architecture/ddd-hexagonal/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: ddd-hexagonal
+description: Use this skill for back-end architecture decisions in projects that selected DDD and Hexagonal Architecture.
+---
+
+# ddd-hexagonal
+
+Use this skill for back-end architecture decisions in projects that selected DDD and Hexagonal Architecture.
+
+Use it when deciding where code belongs, how to structure a feature, whether a port is needed, or how to keep business logic separated from infrastructure.
+
+This skill is backend-focused. It does not cover frontend component architecture, React patterns, or UX concerns.
+
+## Use this skill for
+
+- backend feature design
+- domain/application/infra placement
+- use case design
+- port and adapter decisions
+- repository and external service boundaries
+- server-side refactors that affect architecture
+- reviewing whether backend code respects DDD + Hexagonal Architecture
+
+## Main rule
+
+> **Keep the domain pure, let the application orchestrate, let adapters translate, and keep dependencies pointing inward.**
+
+If a simpler structure preserves clear boundaries, prefer the simpler structure.
+
+## The layers
+
+### Domain
+The domain contains business concepts, rules, and invariants.
+
+Domain should contain:
+- business concepts
+- domain rules
+- invariants
+- domain language
+
+Domain should not contain:
+- framework code
+- database concerns
+- SDK clients
+- filesystem code
+- transport-specific request/response shapes
+
+### Application
+The application layer coordinates use cases.
+
+Application should contain:
+- use cases
+- application orchestration
+- outgoing ports when external capabilities are needed
+- incoming ports when they add clarity
+
+Application should not contain:
+- infrastructure implementations
+- low-level SDK or DB details
+- framework entrypoint logic
+
+### Infrastructure
+Infrastructure contains technical details and adapter implementations.
+
+Infrastructure should contain:
+- repository implementations
+- external API clients
+- SDK integrations
+- filesystem/storage integrations
+- queue or messaging integrations
+
+Infrastructure should not own business rules.
+
+## Dependency rule
+
+> **Dependencies point inward. Implementations point outward.**
+
+This means:
+- driving code depends on the application boundary
+- the application depends on domain concepts and outgoing ports
+- infrastructure depends on application/domain contracts to implement them
+- the domain depends on nothing outside itself
+
+If business logic needs a DB client, SDK response, HTTP object, or framework context directly, the boundary is probably wrong.
+
+## Domain modeling: entity, value object, or neither
+
+Do not force DDD labels onto every concept. Use them only when they buy clarity, express real business meaning, or protect invariants.
+
+### Use an entity when identity matters
+Model something as an entity when:
+- it has continuity over time
+- it can change while remaining the same conceptual thing
+- the business cares which specific instance it is
+- identity matters more than raw field equality
+
+Examples often include users, playlists, subscriptions, or other concepts with lifecycle and identity.
+
+### Use a value object when value and invariants matter
+Model something as a value object when:
+- identity does not matter
+- equality is based on value
+- the concept has validation or invariants worth protecting
+- wrapping a primitive or object makes the domain clearer
+
+Examples often include email addresses, money, ranges, normalized names, or other validated domain values.
+
+### Use neither when the concept is simple and gains little from extra modeling
+Do not create an entity or value object when:
+- the data is simple and obvious
+- there are no meaningful invariants to protect
+- identity is not important
+- a plain type, plain object, or application-level DTO is enough
+- introducing a domain type would add ceremony without improving understanding
+
+### Rule
+> **Prefer the lightest model that preserves meaning and invariants.**
+
+## Practical project mapping
+
+Use this default mapping when the project does not already have a clearer convention:
+
+- `<feature-or-domain>/domain/**` → domain concepts and rules
+- `<feature-or-domain>/application/**` → use cases and application orchestration
+- `<feature-or-domain>/infra/**` → technical implementations and external integrations
+- entrypoints such as routes, jobs, or handlers → thin driving adapters that call application behavior
+
+## Ports and adapters
+
+### Use ports where they buy clarity
+Introduce a port when the application needs a capability but should not depend on its implementation.
+
+Good reasons:
+- isolation
+- testability
+- clearer boundaries
+
+Bad reasons:
+- habit
+- ceremony
+- abstraction for its own sake
+
+### Adapters translate
+Adapters translate between the application model and external systems.
+
+Typical driven adapters:
+- repository implementations
+- external API clients
+- storage clients
+- SDK wrappers
+
+Adapters should hide technical details rather than leak them inward.
+
+## Use cases
+
+A use case should represent one meaningful backend capability.
+
+A use case should:
+- orchestrate domain logic and required ports explicitly
+- stay readable and focused
+- express one meaningful application action
+
+A use case should not:
+- become a dumping ground for unrelated helpers
+- hide infrastructure details inline
+- absorb framework behavior that belongs in adapters
+
+## Simplicity rule
+
+- Use the fewest layers that preserve clear boundaries.
+- Do not add ports, services, or abstractions unless they clearly improve clarity or isolation.
+- Do not split concepts just to look architecturally sophisticated.
+- Architecture should reduce confusion, not create it.
+
+## Boundary tests
+
+When deciding where code belongs, ask:
+
+1. Is this business logic or technical plumbing?
+2. Does this concept exist in the business, or only because of a framework, API, or DB?
+3. Would this code still make sense if we changed the underlying technology?
+4. Is this orchestrating behavior, or implementing a technical detail?
+5. Is this abstraction buying clarity, or only adding indirection?
+
+## Common mistakes
+
+### 1. Putting business logic in entrypoint code
+Route handlers, jobs, or other entrypoints should trigger application behavior, not contain meaningful business rules.
+
+### 2. Letting use cases depend directly on SDKs, DB clients, or framework objects
+This collapses the application boundary.
+
+### 3. Treating every helper as a domain concept
+This makes the domain noisy and artificial.
+
+### 4. Over-abstracting with too many ports and interfaces
+This creates ceremony instead of clarity.
+
+### 5. Letting technical data shapes define the internal model
+This allows infrastructure concerns to leak inward.
+
+### 6. Creating layers without real responsibility
+This grows file structure without improving understanding.
+
+## Practical default
+
+When unsure, prefer:
+1. clear boundaries
+2. simple code
+3. explicit orchestration
+4. minimal necessary abstraction
+5. business concepts over technical leakage

package/templates/skills/clean-code/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: clean-code
+description: Use this skill when writing or modifying code and you need general code-quality guidance.
+---
+
+# clean-code
+
+Use this skill when writing or modifying code and you need general code-quality guidance.
+
+Apply these principles by default unless a more specific repo rule or task requirement overrides them.
+
+## Use this skill for
+
+- writing new code
+- editing existing code
+- reviewing implementation quality
+- simplifying code during an in-scope change
+
+## Core principles
+
+### 1. Prefer clarity over cleverness
+- Write code that is easy to read on the first pass.
+- Avoid surprising control flow, hidden side effects, and dense expressions.
+- If a simpler form exists, prefer it.
+
+### 2. Use clear, descriptive names
+- Names should reveal intent.
+- Prefer names that explain what something represents or does.
+- Avoid unnecessary abbreviations unless they are obvious in context.
+
+#### Prefer
+```ts
+const authenticatedUserId = session.user.id;
+const recommendedTracks = buildRecommendedTracks(seedTracks);
+```
+
+#### Avoid
+```ts
+const uid = session.user.id;
+const recs = buildRecommendedTracks(seedTracks);
+```
+
+### 3. Keep functions focused
+- A function should do one thing well.
+- If a function is doing multiple conceptually different jobs, split it.
+- Keep nested logic shallow when possible.
+
+### 4. Keep control flow simple
+- Prefer straightforward conditionals over clever compact forms.
+- Avoid inline assignments in conditionals.
+- Prefer early returns or clear branching when they improve readability.
+
+#### Prefer
+```ts
+const playlist = await playlistRepository.findById(playlistId);
+
+if (!playlist) {
+  throw new Error("Playlist not found");
+}
+```
+
+#### Avoid
+```ts
+if (!(playlist = await playlistRepository.findById(playlistId))) {
+  throw new Error("Playlist not found");
+}
+```
+
+### 5. Keep the right level of abstraction
+- A function or module should not mix high-level policy with low-level details without a good reason.
+- Keep related concepts together.
+- Separate orchestration from implementation detail when that separation improves understanding.
+
+### 6. Prefer the simplest solution that works
+- Prefer the simplest solution that satisfies the real requirement.
+- Do not add abstraction, indirection, or configurability unless it clearly pays for itself.
+- If a simple solution is sufficient, stop there.
+
+### 7. Avoid duplication with judgment
+- Remove meaningful duplication when it reduces maintenance cost.
+- Do not introduce premature abstractions just to eliminate a small amount of repetition.
+- Prefer a little duplication over the wrong abstraction.
+
+### 8. Comments should add value
+- Prefer code that explains itself.
+- Use comments when they provide context, intent, or rationale that the code alone cannot express.
+- Do not add comments that merely restate the code.
+
+### 9. Make error paths understandable
+- Error handling should be explicit and readable.
+- Add useful context when surfacing errors.
+- Do not hide failure paths in clever expressions.
+
+### 10. Keep changes tidy
+- During a requested change, it is good to remove clearly unused code or obvious local clutter when it is safe and in scope.
+- Leave the touched area cleaner than you found it, without drifting into unrelated refactors.
+
+### 11. Prefer consistency
+- Match the surrounding style when it is already reasonable.
+- Use existing project conventions unless there is a strong reason not to.
+
+## Decision rule
+
+When unsure, prefer:
+1. readability
+2. simplicity
+3. explicitness
+4. small focused units
+5. consistency with the surrounding code

package/templates/skills/feature-brief-writer/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: feature-brief-writer
+description: Use this skill to define business-level feature briefs that stay loyal to docs/product-vision.md before UX, technical design, or implementation work.
+---
+
+# Feature Brief Writer
+
+## Purpose
+
+Create concise feature briefs that explain what a feature is, why it matters, who it serves, and how it follows the product vision required by this skill.
+
+Every feature shaped with this skill must stay loyal to `docs/product-vision.md`: it should support the product's purpose, fit its intended audience, respect its boundaries, and move in the same direction as its success signals.
+
+This skill owns the product/business shape of a feature. It does not own UI interaction design, technical architecture, implementation plans, data models, APIs, or task breakdowns.
+
+## Required source of truth
+
+Before doing any feature-brief work, read:
+
+```txt
+docs/product-vision.md
+```
+
+Use the product vision as the source of truth for the product's purpose, audience, positioning, principles, voice, boundaries, trust expectations, and success signals.
+
+Do not duplicate or rewrite the product vision inside the feature brief. Apply it to the specific feature being defined.
+
+## Hard start rule
+
+Do not start a feature brief if `docs/product-vision.md` is missing.
+
+If the product vision is missing:
+
+1. Stop.
+2. Tell the user that a feature brief requires `docs/product-vision.md`.
+3. Instruct the user to create the product vision first with the `product-vision-writer` skill.
+4. Do not draft, infer, or save a feature brief until the product vision exists.
+
+## Use this skill for
+
+- defining a new feature at the business/product level
+- turning a rough feature idea into a scoped feature brief
+- clarifying user value, product fit, and business rationale
+- deciding MVP vs later scope at a product level
+- identifying non-technical risks, assumptions, dependencies, and tradeoffs
+- defining business-level acceptance criteria
+- checking whether a feature fits the product vision
+
+## Output location
+
+When asked to create a file, write the feature brief to:
+
+```txt
+docs/features/<feature-slug>/feature_brief.md
+```
+
+Use a short kebab-case feature slug that matches the feature name. Keep all artifacts for the same feature together under `docs/features/<feature-slug>/`.
+
+Do not write the brief to technical design, UX, user story, implementation plan, or backlog files unless the user explicitly asks for a separate artifact after the feature brief exists.
+
+## Workflow
+
+### 1. Read the product vision
+
+Read `docs/product-vision.md` first and identify:
+
+- the product's core promise
+- target users and scenarios
+- product positioning
+- product principles
+- boundaries and anti-goals
+- trust, quality, or voice expectations
+- success signals
+
+Use these as constraints for the feature brief.
+
+### 2. Clarify vague feature intent before drafting
+
+Do not draft a feature brief from a vague request.
+
+A request is too vague when the user gives only a broad area, product milestone, theme, or label such as "define the MVP," "write the onboarding feature," "make a sync feature," or "I want analytics" without enough detail to know what the user actually means.
+
+When feature intent is vague:
+
+1. Stop before drafting.
+2. Explain briefly that the feature direction needs clarification before a responsible brief can be written.
+3. Ask one focused discovery question.
+4. Wait for the user's answer.
+5. Continue asking one question at a time until there is enough context to write a useful, product-vision-aligned brief.
+
+Do not ask the user to answer a large questionnaire all at once. Keep the interview conversational and focused.
+
+### 3. Gather the minimum required feature context
+
+Ask only for missing information that materially affects the brief. Prefer the fewest questions needed to produce a useful document, but ask as many one-at-a-time questions as needed when the feature is underdefined.
+
+Clarify:
+
+- what feature or capability the user wants
+- what the user means by broad labels such as MVP, onboarding, sync, analytics, or automation
+- what user or business problem it addresses
+- who the feature is for
+- when and why the target user would use it
+- what outcome should improve
+- what must be included in the first version
+- what should stay out of scope
+- known constraints, risks, or open decisions
+
+Only move to drafting once the feature intent, target user or scenario, desired outcome, and rough MVP boundary are clear enough to avoid inventing the product direction.
+
+### 4. Write a business-level brief
+
+Write in Markdown. Keep the brief clear, decision-oriented, and non-technical.
+
+Recommended structure:
+
+```md
+# <Feature Name> Feature Brief
+
+## Summary
+<One-paragraph description of the feature and why it matters.>
+
+## Product Vision Fit
+<How this feature supports the product vision, principles, audience, or positioning.>
+
+## User / Customer Problem
+<The user need, pain, desire, or opportunity this feature addresses.>
+
+## Business Goal
+<The product or business outcome this feature should improve.>
+
+## Target User / Scenario
+<Who this is for and when they would use it.>
+
+## Proposed Experience
+<Business-level user experience, not implementation details.>
+
+## MVP Scope
+- <What belongs in the first useful version.>
+
+## Out of Scope
+- <What is intentionally excluded for now.>
+
+## Success Signals
+- <Observable user, product, or business signals that indicate the feature is working.>
+
+## Business-Level Acceptance Criteria
+- <Testable product behavior or outcome, stated without technical implementation details.>
+
+## Risks / Tradeoffs
+- <Important product, user, trust, operational, or positioning risks.>
+
+## Open Questions
+- <Decisions that still need user/product input.>
+```
+
+Adapt the structure to the feature. Add, rename, merge, or omit sections when useful, but keep the result business-level and product-vision-aligned.
+
+### 5. Keep technical detail out
+
+Do not include:
+
+- architecture diagrams
+- implementation plans
+- database schemas
+- API contracts
+- library choices
+- engineering task lists
+- UI wireframes or detailed interaction specs
+
+If technical or UX decisions come up, capture them as brief product-level constraints or open questions.
+
+### 6. Save the document
+
+Create the feature directory if needed and save the document at:
+
+```txt
+docs/features/<feature-slug>/feature_brief.md
+```
+
+If the file already exists, read it first. Treat the request as a revision when the user asks to revise, clarify, or update the feature brief. Ask before overwriting an existing brief when the user appears to be asking for a separate new feature.
+
+## Writing style
+
+Aim for writing that is:
+
+- loyal to the required product vision
+- specific to the user's feature
+- grounded in the product vision
+- concise
+- opinionated enough to guide later decisions
+- understandable by non-engineering stakeholders
+
+Avoid:
+
+- generic startup language
+- technical implementation detail
+- vague benefits without user or business grounding
+- feature lists without rationale
+- drafting from vague feature labels without discovery
+- inventing certainty where the product vision or user input is unresolved
+
+## Decision rule
+
+When shaping a feature brief, prefer:
+
+1. alignment with `docs/product-vision.md`
+2. clear user value
+3. clear business or product outcome
+4. simple MVP scope
+5. honest boundaries and tradeoffs
+6. measurable success signals
+7. non-technical acceptance criteria
+
+## Final response behavior
+
+After writing the file, briefly report the path that was created or updated. Include the full feature brief in the response only if the user asks to review it inline.
+
+If file writes are unavailable, provide the Markdown content and state that it is intended for `docs/features/<feature-slug>/feature_brief.md`.

package/templates/skills/golang/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: golang
+description: Use this skill when writing or modifying Go files and you need practical Go guidance grounded in Effective Go and standard Go conventions.
+---
+
+# golang
+
+Use this skill when writing or modifying `.go` files and you need practical Go guidance.
+
+Apply this skill together with `clean-code`. Keep this skill focused on Go-specific decisions, not generic code-quality advice.
+
+## Use this skill for
+
+- writing new Go code
+- editing existing Go packages
+- shaping package APIs
+- choosing between structs, interfaces, methods, and functions
+- writing idiomatic Go error handling, concurrency, and tests
+
+## Core principles
+
+### 1. Follow Go's default shape
+- Let `gofmt` and standard Go conventions decide most formatting.
+- Prefer short, clear names that match common Go usage.
+- Use lowercase package names with no underscores when possible.
+- Favor the standard library before adding dependencies.
+
+### 2. Keep packages small and APIs narrower than implementations
+- Organize code around packages with clear responsibilities.
+- Keep exported surface area small.
+- Export only what callers truly need.
+
+### 3. Prefer concrete types and useful zero values
+- Design structs so the zero value is useful when practical.
+- Prefer plain structs and functions over unnecessary constructors or class-like patterns.
+- Avoid pointers unless mutation, sharing, interface contracts, or copy cost justify them.
+- Return concrete types unless callers truly benefit from an interface.
+
+### 4. Keep interfaces small and define them where they are used
+- Prefer tiny behavior-focused interfaces, often with one or two methods.
+- Usually define interfaces in the consuming package, not the implementing package.
+- Do not introduce interfaces just for future flexibility or mocking.
+- Accept interfaces when you need abstraction; return concrete types when you can.
+
+### 5. Handle errors explicitly
+- Return `error` for expected failure paths.
+- Add context with wrapping, such as `fmt.Errorf("read config: %w", err)`.
+- Use sentinel errors or typed errors only when callers need branching behavior.
+- Do not use `panic` for normal control flow.
+
+### 6. Choose methods and receivers deliberately
+- Use value receivers for small immutable-like values.
+- Use pointer receivers when methods mutate state, the type is large, or receiver consistency matters.
+- Keep receiver style consistent for a given type.
+- Prefer functions over methods when behavior does not depend on receiver state.
+
+### 7. Keep control flow straightforward
+- Prefer early returns for error handling.
+- Use `switch` when it reads better than long `if` chains.
+- Use `for` and `range` directly instead of trying to simulate other loop styles.
+- Keep `defer` close to the resource acquisition it cleans up.
+
+### 8. Use concurrency only when it clarifies or improves the design
+- Do not add goroutines or channels unless they solve a real coordination or latency problem.
+- Use `context.Context` for cancellation, deadlines, and request-scoped work.
+- Be explicit about goroutine lifetime and shutdown paths.
+- Prefer simple ownership and communication over shared mutable state.
+
+### 9. Write table-driven tests when they improve coverage and readability
+- Prefer small, focused tests in the same package unless external-package tests add value.
+- Use table-driven tests for repeated input/output cases.
+- Keep test cases named so failures explain themselves.
+- Test exported behavior and important package contracts, not private implementation trivia.
+
+## Decision rule
+
+When unsure, prefer:
+1. standard library and Go conventions
+2. smaller package APIs
+3. concrete types over premature interfaces
+4. explicit error handling
+5. simple sequential code before concurrency