npm - @juancr11/sibu - Versions diffs - 0.1.0 - Mend

@juancr11/sibu 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/README.md +198 -0
package/bin/entrypoints/cli/command.js +1 -0
package/bin/entrypoints/cli/create-program.js +33 -0
package/bin/entrypoints/cli/execute-command.js +28 -0
package/bin/entrypoints/cli/main.js +5 -0
package/bin/features/doctor-project/command.js +1 -0
package/bin/features/doctor-project/handler.js +194 -0
package/bin/features/init-project/command.js +1 -0
package/bin/features/init-project/handler.js +63 -0
package/bin/features/list-skills/command.js +1 -0
package/bin/features/list-skills/handler.js +55 -0
package/bin/features/stop-managing-file/command.js +1 -0
package/bin/features/stop-managing-file/handler.js +213 -0
package/bin/features/sync-project/action-prompt.js +65 -0
package/bin/features/sync-project/apply-action.js +81 -0
package/bin/features/sync-project/command.js +1 -0
package/bin/features/sync-project/handler.js +77 -0
package/bin/features/sync-project/log-preview.js +62 -0
package/bin/features/sync-project/preview.js +1 -0
package/bin/features/use-skill/command.js +1 -0
package/bin/features/use-skill/handler.js +197 -0
package/bin/shared/catalog.js +199 -0
package/bin/shared/hash.js +11 -0
package/bin/shared/npm-version.js +178 -0
package/bin/shared/object.js +3 -0
package/bin/shared/paths.js +41 -0
package/bin/shared/prompts.js +205 -0
package/bin/shared/state.js +76 -0
package/bin/shared/sync-preview.js +166 -0
package/bin/shared/templates.js +60 -0
package/bin/shared/types.js +1 -0
package/bin/shared/workflow-mutation-readiness.js +30 -0
package/bin/shared/workflow-targets.js +119 -0
package/bin/sibu.js +6 -0
package/package.json +68 -0
package/templates/.codex/config.toml +1 -0
package/templates/AGENTS.md +60 -0
package/templates/CLAUDE.md +5 -0
package/templates/GEMINI.md +5 -0
package/templates/manifest.json +129 -0
package/templates/skills/ai-implementation-plan-executor/SKILL.md +138 -0
package/templates/skills/ai-implementation-planner/SKILL.md +213 -0
package/templates/skills/architecture/command-pattern/SKILL.md +77 -0
package/templates/skills/architecture/ddd-hexagonal/SKILL.md +212 -0
package/templates/skills/clean-code/SKILL.md +109 -0
package/templates/skills/feature-brief-writer/SKILL.md +219 -0
package/templates/skills/golang/SKILL.md +82 -0
package/templates/skills/nextjs/SKILL.md +94 -0
package/templates/skills/product-vision-writer/SKILL.md +128 -0
package/templates/skills/react/SKILL.md +75 -0
package/templates/skills/scrum-master-planner/SKILL.md +191 -0
package/templates/skills/technical-design-writer/SKILL.md +109 -0
package/templates/skills/typescript/SKILL.md +111 -0

package/templates/skills/nextjs/SKILL.md ADDED Viewed

@@ -0,0 +1,94 @@
+---
+name: nextjs
+description: Use this skill when working on Next.js App Router files or framework-specific Next.js behavior.
+---
+# nextjs
+Use this skill when working on Next.js App Router files or framework-specific Next.js behavior.
+This skill covers Next.js conventions, boundaries, and rendering decisions. It does not cover React component design or UX strategy.
+## Use this skill for
+- `src/app/**` pages, layouts, route handlers, loading, error, and not-found files
+- Server Component vs Client Component decisions
+- Next.js data fetching and rendering placement
+- route handler conventions
+- metadata APIs
+- App Router file conventions
+- framework boundary decisions in Next.js files
+## Core principles
+### 1. Use App Router conventions directly
+- Put route UI in `page.tsx`.
+- Put shared route shell UI in `layout.tsx`.
+- Put custom request handlers in `route.ts`.
+- Use `loading.tsx`, `error.tsx`, and `not-found.tsx` for route segment states when they improve the user experience.
+- Keep special files focused on their framework role.
+### 2. Default to Server Components
+- Pages and layouts are Server Components by default.
+- Keep them as Server Components unless interactivity or browser-only APIs require a Client Component.
+- Fetch initial and SEO-critical data on the server when possible.
+- Pass only serializable props from Server Components to Client Components.
+### 3. Use Client Components only when needed
+Add `"use client"` only for code that needs client-side capabilities, such as:
+- state and event handlers
+- effects or lifecycle behavior
+- browser-only APIs like `window`, `localStorage`, or geolocation
+- client-only third-party components
+Prefer isolating the smallest interactive subtree into a Client Component rather than turning a whole page or layout into a Client Component.
+### 4. Keep `src/app/**` thin
+- Treat `src/app/**` as a framework boundary.
+- Pages and route handlers should call application/domain code instead of containing business logic.
+- Keep request parsing, response formatting, redirects, and framework concerns in `src/app/**`.
+- Move reusable business behavior out of App Router files.
+### 5. Route handlers are framework adapters
+- Define route handlers in `route.ts` files inside `app`.
+- Use the Web `Request` and `Response` APIs.
+- Keep handlers focused on HTTP concerns: parse input, call application behavior, and return a stable response.
+- Do not put backend business rules directly in route handlers.
+### 6. Use Next.js error and empty-state conventions
+- Use `notFound()` for route resources that genuinely do not exist.
+- Add `not-found.tsx` when a route segment needs a custom 404 UI.
+- Add `loading.tsx` when a route segment benefits from an instant loading state.
+- Add `error.tsx` for unexpected runtime errors in a route segment.
+- Remember that `error.tsx` must be a Client Component.
+### 7. Separate expected errors from unexpected errors
+- Treat expected errors, such as validation failures, not-found cases, and user-correctable failures, as explicit states or return values.
+- Let unexpected errors throw so route-level error boundaries can handle them.
+- Keep client-safe messages in UI responses and logs/internal details at the server boundary.
+### 8. Use metadata APIs instead of manual `<head>` tags
+- Use `metadata` or `generateMetadata` for route metadata.
+- Do not manually add `<title>` or `<meta>` tags in root layouts.
+- Use file-based metadata conventions for icons, Open Graph images, robots, sitemap, and related files when appropriate.
+### 9. Keep rendering and data ownership clear
+- Server Components can fetch and prepare data for rendering.
+- Client Components should own interaction state and browser behavior.
+- Avoid duplicating derived state between server-rendered data and client state.
+- Do not move data fetching to the client unless it is user-triggered, browser-specific, or intentionally client-side.
+### 10. Prefer simple route segment design
+- Use route groups and advanced routing features only when they clearly improve organization or behavior.
+- Do not introduce parallel routes, intercepting routes, templates, or segment config unless the feature actually needs them.
+- Prefer the standard App Router primitives first.
+## Decision rule
+When unsure, prefer:
+1. Server Components by default
+2. the smallest necessary Client Component boundary
+3. App Router files as thin framework adapters
+4. framework conventions over custom routing abstractions
+5. `metadata` / `generateMetadata` over manual head management
+6. explicit loading, not-found, and error states when the route needs them

package/templates/skills/product-vision-writer/SKILL.md ADDED Viewed

@@ -0,0 +1,128 @@
+---
+name: product-vision-writer
+description: Create product vision documents for products at any stage. Use when an assistant should interview the user with focused discovery questions, clarify product purpose, audience, positioning, principles, boundaries, voice, trust expectations, and success signals, then synthesize the answers into a human, opinionated, structured Markdown product vision document at docs/product-vision.md.
+---
+# Product Vision Writer
+## Purpose
+Help write product vision documents that make a product feel clear, intentional, and worth building. Work for any product domain and any product stage.
+Default output path: `docs/product-vision.md`.
+## Workflow
+### 1. Start with discovery, not drafting
+Ask focused questions before writing the document unless the user has already provided enough source material.
+Ask one question at a time. Wait for the user's answer before asking the next discovery question.
+Prefer the fewest questions that can produce a useful document. Ask follow-ups only when an answer materially changes the document or when a critical input is missing.
+Cover these areas over the course of the interview:
+- **Product essence:** What is the product? What should it help people do, feel, or become?
+- **Current context:** Is this a new concept, an active project, or an existing product?
+- **Target user:** Who is it for? What is true about their life, work, habits, or desires?
+- **Core problem or desire:** What pain, need, ambition, or emotional gap does the product address?
+- **Emotional promise:** What should the ideal user reaction be?
+- **Positioning:** What is this product compared against, and how should it feel different?
+- **Product philosophy:** What principles should guide product decisions?
+- **User control:** How much should users configure, decide, or manage?
+- **Trust and quality:** What must the product be honest about? Where can it be imperfect?
+- **Product voice:** How should the product sound? What language should it avoid?
+- **Boundaries:** What should the product not become?
+- **Success signal:** What behavior or outcome proves the product is working?
+When helpful, ask for examples of products, experiences, media, brands, or moments the user wants the product to feel like or avoid.
+### 2. Synthesize before structuring
+Before drafting, infer the product's through-line:
+- the central promise
+- the main user tension
+- the strongest differentiation
+- the product's opinion about the world
+- the decision-making principles that should survive future feature debates
+If the user's answers conflict, resolve the conflict explicitly in the draft by choosing the clearest product direction. Do not preserve every idea equally.
+### 3. Draft the product vision document
+Write in Markdown. Use clear headings, short paragraphs, and bullets where they improve readability.
+Recommended structure:
+```markdown
+# <Product Name> Product Vision
+## Summary
+## Product North Star
+## Target User
+## Product Positioning
+## Product Philosophy
+## User Control
+## Trust and Quality
+## Product Voice
+## What <Product Name> Should Not Become
+## Success Signal
+```
+Adapt sections to the product. Add, rename, merge, or omit sections when useful.
+### 4. Write in the right style
+Aim for writing that is:
+- human
+- opinionated
+- concrete
+- concise
+- emotionally clear
+- useful for decision-making
+- free of generic startup language
+Avoid:
+- corporate fluff
+- vague claims like “seamless,” “innovative,” or “leveraging technology” unless grounded in specifics
+- overexplaining
+- feature lists masquerading as vision
+- excessive frameworks
+- pretending unresolved strategy questions are settled
+Use the user's own language when it is vivid or revealing. Improve clarity without sanding off personality.
+### 5. Handle incomplete inputs
+If the user has only a rough idea, produce a sharper first-pass vision with clearly stated assumptions.
+If the user has an existing product, make the document reflect what the product is today and what it must protect or change.
+If there is not enough context to write responsibly, ask the smallest possible follow-up question set instead of inventing details.
+### 6. Save the document
+When working in a repository, write the product vision document to `docs/product-vision.md` by default. Create the `docs/` directory if needed.
+If `docs/product-vision.md` already exists, read it before drafting. Treat the request as a revision when the user asks to revise, clarify, or update the product vision. Ask before overwriting an existing document when the user appears to be asking for a separate new product vision.
+If the user explicitly requests a different path, use that path instead.
+### 7. Final response behavior
+After writing the file, briefly report the path that was created or updated. Include the full document 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/product-vision.md`.

package/templates/skills/react/SKILL.md ADDED Viewed

@@ -0,0 +1,75 @@
+---
+name: react
+description: Use this skill when working on React components and component design.
+---
+# react
+Use this skill when working on React components and component design.
+This skill covers React componentization, component responsibility, state ownership, and presentation-vs-interaction boundaries.
+## Use this skill for
+- creating or editing React components
+- splitting large components
+- deciding where state should live
+- separating presentational components from server-interacting or data-owning components
+- reviewing component responsibility and prop design
+## Core principles
+### 1. Treat components like focused functions
+- A component should have one clear reason to exist.
+- If a component does too many unrelated things, split it.
+- Prefer small components with clear names and explicit responsibilities.
+- Do not split components just to create more files; split when it improves understanding.
+### 2. Separate presentational components from data-owning components
+- Presentational components should mostly render UI from props.
+- Data-owning components may fetch, subscribe, mutate, or coordinate data.
+- Keep it obvious which components interact with the server and which are purely presentational.
+- Avoid hiding server interactions deep inside components that look presentational.
+### 3. Keep props narrow and explicit
+- Pass only what the child component needs.
+- Prefer specific props over large loosely typed objects.
+- Use prop names that describe component intent, not implementation details.
+- Avoid prop drilling when it makes the component tree hard to understand; do not add context prematurely.
+### 4. Keep render logic pure
+- Rendering should depend on props, state, and context.
+- Do not mutate external values during render.
+- Keep side effects out of render logic.
+- Calculate derived values during render when they are cheap and deterministic.
+### 5. Put state at the right level
+- Keep state local when only one component needs it.
+- Lift state to the closest common parent when multiple components need to coordinate.
+- Avoid duplicating derived state that can be computed from props or existing state.
+- Prefer a single clear source of truth.
+### 6. Isolate interactivity
+- Keep interactive behavior close to the component that owns it.
+- If only a small part of the UI needs interactivity, isolate that part instead of making a larger tree interactive.
+- Separate event handling from presentation when doing so makes responsibility clearer.
+### 7. Prefer composition over configuration-heavy components
+- Compose smaller components instead of building one component with many modes and flags.
+- If a component needs many boolean props, consider whether it is doing too much.
+- Use `children` or named subcomponents when composition makes the API clearer.
+### 8. Make component boundaries visible
+- Name components by what they represent in the UI or product.
+- Keep server-interacting, stateful, and presentational responsibilities easy to identify from the component shape.
+- Avoid mixing data fetching, mutation, layout, formatting, and low-level UI rendering in one component.
+## Decision rule
+When unsure, prefer:
+1. one clear responsibility per component
+2. presentational components that render from props
+3. data/server interaction in obvious owner components
+4. local state unless coordination requires lifting it
+5. composition over flag-heavy component APIs
+6. no duplicated derived state

package/templates/skills/scrum-master-planner/SKILL.md ADDED Viewed

@@ -0,0 +1,191 @@
+---
+name: scrum-master-planner
+description: Create pragmatic Epics and User Stories from an approved feature brief and technical design. Use when asked to plan delivery, create epics, write user stories, split a feature into backlog work, or turn a feature brief plus technical design under docs/features into Scrum planning artifacts.
+---
+# Scrum Master Planner
+## Purpose
+Turn an approved feature brief and technical design into the smallest useful Scrum planning structure: Epics and User Stories that are clear enough for a team to implement and validate.
+This skill owns delivery planning artifacts. It does not own product vision, feature definition, technical design, code implementation, or project-management tool automation.
+## Required inputs
+Before planning, read:
+```txt
+docs/features/<feature-slug>/feature_brief.md
+docs/features/<feature-slug>/technical_design.md
+```
+Also read `docs/product-vision.md` when it exists and the planning decision depends on product fit, scope boundaries, user value, or success signals.
+## Hard start rule
+Do not create Epics or User Stories if either the feature brief or technical design is missing.
+If an input is missing:
+1. Stop.
+2. Say which file is missing.
+3. Ask the user to create the missing artifact first.
+4. Do not invent planning scope from partial context.
+## Output locations
+For a feature at:
+```txt
+docs/features/<feature-slug>/feature_brief.md
+```
+write Epics and User Stories under:
+```txt
+docs/features/<feature-slug>/epics/<epic-slug>/epic_brief.md
+docs/features/<feature-slug>/epics/<epic-slug>/stories/<order>-<user-story-slug>.md
+```
+Rules:
+- Every User Story must belong to exactly one Epic.
+- Never create orphan User Stories outside an Epic folder.
+- Use kebab-case slugs for Epic folders and User Story filenames.
+- Prefix every User Story filename with a two-digit execution order within its Epic, such as `01-`, `02-`, or `03-`.
+- Use the same order number for User Stories that can be developed in parallel within the same Epic.
+- Keep all artifacts for the feature under the same `docs/features/<feature-slug>/` tree.
+## Planning rule
+Create the smallest useful planning structure.
+If one Epic with one User Story fully captures the work, create one Epic and one User Story. Add more Epics or User Stories only when there are meaningfully distinct outcomes, delivery slices, risks, dependencies, validation paths, or contributor ownership boundaries.
+Avoid Agile theater. Do not create multiple Epics or Stories just because Scrum artifacts usually appear in groups.
+## Workflow
+### 1. Read source artifacts
+Identify from the feature brief:
+- user/customer problem
+- MVP scope
+- out-of-scope boundaries
+- success signals
+- business-level acceptance criteria
+Identify from the technical design:
+- implementation slices
+- affected commands, files, modules, integrations, or docs
+- validation expectations
+- meaningful risks or unresolved decisions
+### 2. Choose Epic boundaries
+Create Epics around coherent delivery outcomes, not technical layers.
+Good Epic boundaries include:
+- a user-visible capability
+- a complete CLI workflow
+- a self-contained documentation or planning outcome
+- a risk-reduction slice needed before broader work
+- a contributor-owned chunk that can be reviewed independently
+Avoid Epics that are only generic layers such as “frontend,” “backend,” “tests,” or “refactor” unless the source docs explicitly make that the delivery outcome.
+### 3. Write each Epic brief
+Each `epic_brief.md` should use this structure:
+```md
+# <Epic Name> Epic Brief
+## Summary
+<What outcome this Epic delivers and why it matters.>
+## Source Context
+- Feature brief: <relative path>
+- Technical design: <relative path>
+## Scope
+- <What belongs in this Epic.>
+## Out of Scope
+- <What this Epic intentionally does not cover.>
+## User Stories
+- [<Story title>](./stories/<order>-<user-story-slug>.md)
+## Acceptance Criteria
+- <Epic-level criteria that prove the outcome is complete.>
+## Dependencies / Risks
+- <Only meaningful dependencies, risks, or sequencing notes.>
+```
+Adapt headings only when it improves clarity. Keep the Epic brief short.
+### 4. Sequence and write User Stories
+Within each Epic, decide the order of execution before writing User Story files. Use the lowest practical sequence number for the first story that should be implemented, then increment only when later stories depend on earlier work. If two or more stories can be developed at the same time, give them the same order number.
+Each User Story should be independently understandable and should represent a reviewable slice of work.
+Use this structure:
+```md
+# <User Story Title>
+## Epic
+[<Epic Name>](./epic_brief.md)
+## User Story
+As a <user or contributor>, I want <capability or outcome>, so that <value or reason>.
+## Context
+<Brief source-grounded context.>
+## Scope
+- <What this story includes.>
+## Out of Scope
+- <What this story excludes.>
+## Acceptance Criteria
+- <Observable, testable behavior or artifact.>
+## Validation
+- <Manual or automated checks from the technical design.>
+## Notes
+- <Optional implementation, sequencing, or risk notes. Omit if not useful.>
+```
+Keep Stories concrete, but do not turn them into implementation plans or task checklists. If detailed implementation guidance is needed, point to the technical design instead of restating it.
+### 5. Check coverage and boundaries
+Before finishing, verify:
+- every MVP scope item from the feature brief is covered by at least one Epic or Story, or intentionally left out with a reason
+- every Story belongs to exactly one Epic
+- every Story filename includes a two-digit execution order prefix
+- Stories with the same order number are actually parallelizable
+- Story count is pragmatic, not inflated
+- no Story adds scope that is absent from the feature brief or technical design
+- acceptance criteria are testable enough for a reviewer
+## Final response behavior
+After writing files, briefly report:
+- the Epic directories created or updated
+- the number of Epics and User Stories
+- any source-scope items intentionally left unresolved or captured as risks
+Do not paste all generated artifacts unless the user asks to review them inline.

package/templates/skills/technical-design-writer/SKILL.md ADDED Viewed

@@ -0,0 +1,109 @@
+---
+name: technical-design-writer
+description: Use this skill to turn an approved feature brief into a concise, implementation-oriented technical design that delegates code-quality and architecture details to the relevant skills instead of restating them.
+---
+# technical-design-writer
+Write the smallest useful technical design doc for an approved feature.
+The doc should help a human say, “cool, I understand the implementation direction,” and help a later coding agent say, “nice, I know what to do next.” Avoid filler, generic engineering advice, and restating other skills.
+## Grounding
+Before writing, read:
+1. `docs/product-vision.md`
+2. the feature brief
+3. `clean-code`
+4. any selected architecture, language, or framework skills that apply
+5. relevant existing repo files and flows
+Apply those inputs. Do not summarize them back into the technical design unless a specific implication changes the implementation.
+## Required input
+Require a Markdown feature brief. If the user only has a vague idea, route to `feature-brief-writer` first.
+If the feature has UI impact, use an existing UX artifact when available. If missing, note the UI uncertainty briefly instead of inventing UX.
+## Design stance
+Translate product intent into implementation direction.
+Prefer:
+- concise decisions over long explanation
+- concrete file/module impact over abstract architecture language
+- current codebase patterns over speculative redesigns
+- explicit open questions over risky assumptions
+- delegation to the right skills instead of duplicating their guidance
+Avoid:
+- restating clean-code, architecture, language, or framework principles
+- product scope expansion
+- user stories, tickets, or delivery plans
+- invented CLI/database/API concepts that the feature brief did not ask for
+- large template sections that say “none” without adding value
+## Delegation rule
+A technical design may name the skills that later implementation should use, but it should not repeat their contents.
+Examples:
+- Good: “Implementation should follow `command-pattern` for the new `sibu skills use` command slice.”
+- Bad: restating the full command/handler/port responsibilities from the `command-pattern` skill.
+- Good: “Use `clean-code` during implementation; no extra code-quality rules are introduced here.”
+- Bad: adding a generic clean-code checklist to the doc.
+## Workflow
+1. Read the required grounding artifacts.
+2. Inspect the relevant existing code before proposing changes.
+3. Identify only the implementation decisions that matter.
+4. Write the doc at `docs/features/<feature-slug>/technical_design.md`.
+5. Keep it concise. Remove any section that does not help implementation.
+## Output location
+Always create or update:
+```txt
+docs/features/<feature-slug>/technical_design.md
+```
+Use the same kebab-case feature slug as the feature brief.
+## Output format
+Use this structure as a starting point, not a contract. Delete sections that do not add value.
+```md
+# Technical Design: <Feature Name>
+## Inputs
+- Product vision: <path>
+- Feature brief: <path>
+- Delegated skills: <skills later implementation should apply>
+## Summary
+<2-4 sentences describing the implementation direction.>
+## Existing Context
+<Only the current files, commands, modules, state, templates, or integrations that materially affect the change.>
+## Proposed Design
+<Concrete implementation decisions. Include command flows, file/module impact, state changes, and integration boundaries when relevant.>
+## Validation
+<Focused test/build/manual checks.>
+## Risks / Open Questions
+- <Only unresolved decisions or meaningful risks.>
+```
+## Quality bar
+A good technical design is short, specific, and useful. It should not try to be the product brief, architecture skill, clean-code skill, implementation plan, or ticket backlog.