Sibu

Sibu helps developers set up and maintain an AI-augmented development workflow without handing the steering wheel to the machine.

It gives your repo a practical workflow kit: shared agent instructions, focused skills, safety rules, MCP configuration, template health checks, and sync guidance that help you move faster while keeping local control.

If your AI setup is a pile of copied prompts, half-updated agent files, and “I think this is how we do it now” conventions, Sibu is the reset button.

Why Sibu exists

AI-assisted development is moving fast. The hard part is no longer finding one more model, editor, agent, or prompt. The hard part is turning all of that motion into a workflow your future self and your team can trust.

Sibu is a CLI companion for that job. It helps you:

• bootstrap consistent AI workflow files in a project
• select the agents, skills, and MCP servers your repo should support
• check whether managed workflow files are missing, modified, or stale
• review template updates without silently overwriting local edits
• keep AI work small, explicit, reviewable, and human-owned

Sibu is not an AI IDE. It is not an autopilot. It is a grounded workflow layer for engineers who want speed without slop.

Quickstart

Install Sibu globally with npm:

npm install -g @juancr11/sibu

Then run the normal first-use flow from the project you want to equip with an AI workflow:

sibu init
sibu doctor
sibu sync

What happens:

1. sibu init creates or records the starting workflow files for your selected agents, skills, and MCP servers.
2. sibu doctor runs a read-only health check for missing files, local modifications, template drift, and package update advice.
3. sibu sync lets you review drift and template updates interactively before anything changes.

Updating the Sibu npm package does not automatically change project files. It only updates the CLI and bundled templates that sibu doctor can compare against. Your repo changes only when you explicitly initialize, sync, add/remove supported workflow pieces, or choose a mutating action.

Core commands

sibu init

Run this once in a project to adopt Sibu:

sibu init

init opens an interactive setup flow, lets you choose supported agents and optional workflow pieces, creates missing support files, preserves existing files, and records managed workflow metadata in .sibu/state.json.

If AGENTS.md is missing, Sibu asks for a project overview and writes one from the bundled template. If files already exist, Sibu keeps them intact instead of pretending it owns your repo.

sibu doctor

Run a read-only health check:

sibu doctor

doctor reports workflow state without changing files. It can identify missing managed files, local modifications, malformed state metadata, template version drift, unsupported selections, and npm update advice.

If doctor says a newer Sibu version exists, update the CLI and check again:

npm install -g @juancr11/sibu
sibu doctor

A package update may let doctor detect newer templates, but it still will not mutate your project. If drift appears, decide whether to review it with sibu sync.

sibu sync

Review and apply workflow maintenance actions:

sibu sync

sync explains what changed, protects local edits from automatic overwrites, and lets you choose safe actions such as applying an update, recreating a missing managed file, writing a side template for comparison, marking a customized file as reviewed, stopping management, or skipping for later.

Sibu records managed files as managed, customized, or unmanaged in .sibu/state.json, so the project remains transparent about what Sibu tracks and what you own directly.

sibu skills

List available workflow skills and see what is selected:

sibu skills list

Stop managing a selected skill file when it no longer fits the project:

sibu skills stop <file>

Sibu updates state, removes the selected skill when applicable, and asks whether to keep or delete the local file.

sibu mcp

List, add, or stop supported MCP server configuration:

sibu mcp list
sibu mcp use github
sibu mcp stop github

Sibu writes supported agent config files, but runtime prerequisites, credentials, provider login, and permissions remain yours.

The Sibu Workflow Loop

Sibu works best when AI collaboration stays small, explicit, and reviewable. The loop is the rhythm: orient before building, build in focused slices, validate the result, and keep the workflow healthy over time.

flowchart LR
  orient["1. Orient<br/>Product vision + module map"] --> design["2. Design<br/>Feature brief + technical design"]
  design --> plan["3. Plan<br/>Epics, stories + implementation steps"]
  plan --> build["4. Build<br/>Small AI-assisted changes"]
  build --> validate["5. Validate<br/>Tests, checks + human review"]
  validate --> maintain["6. Maintain<br/>doctor + sync"]
  maintain --> orient

| Stage | What it means | | --- | --- | | Orient | Clarify the product promise, boundaries, and deep modules so AI work starts with context instead of vibes. | | Design | Turn a feature idea into a brief and technical direction before implementation details sprawl. | | Plan | Split work into epics, stories, and implementation steps small enough for reviewable AI collaboration. | | Build | Let agents help with focused changes while the engineer keeps scope and judgment. | | Validate | Run checks, inspect output, and require human approval before treating work as done. | | Maintain | Use sibu doctor and sibu sync to keep workflow files current without silently overwriting local choices. |

This is not ceremony for ceremony's sake. It is how Sibu keeps velocity from turning into slop.

Skills Inventory

Skills are reusable instructions that teach an AI agent how to handle a focused kind of work. Sibu uses them to keep prompts smaller, workflows clearer, and responsibilities explicit.

flowchart TB
  skills["Sibu skills"]

  skills --> product["Product + planning"]
  product --> productVision["product-vision-writer"]
  product --> deepModuleMap["deep-module-map-writer"]
  product --> featureBrief["feature-brief-writer"]
  product --> scrumPlanner["scrum-master-planner"]

  skills --> designDelivery["Design + delivery"]
  designDelivery --> technicalDesign["technical-design-writer"]
  designDelivery --> implementationPlanner["ai-implementation-planner"]
  designDelivery --> implementationExecutor["ai-implementation-plan-executor"]

  skills --> engineering["Engineering guidance"]
  engineering --> cleanCode["clean-code"]
  engineering --> typescript["typescript"]
  engineering --> commandPattern["command-pattern"]

  skills --> promptsMaintenance["Prompts + workflow maintenance"]
  promptsMaintenance --> promptEngineer["ai-prompt-engineer-master"]
  promptsMaintenance --> templateChange["sibu-template-change"]

| Skill | Helps with | Use when... | | --- | --- | --- | | product-vision-writer | Product vision and positioning | You need to define or revise the product north star, audience, boundaries, voice, or success signals. | | deep-module-map-writer | Deep implementation boundaries | You need to map durable modules before feature work, or decide where future work belongs. | | feature-brief-writer | Business-level feature definition | You need a scoped feature brief grounded in the product vision and Deep Module Map. | | technical-design-writer | Implementation-oriented design | You have an approved feature brief and need a concise technical direction before planning stories. | | scrum-master-planner | Epics and user stories | You need to split an approved feature brief and technical design into pragmatic delivery slices. | | ai-implementation-planner | Story implementation steps | You need an approved user story turned into small, executable implementation-plan files. | | ai-implementation-plan-executor | Plan execution | You want an agent to execute a story implementation plan, stop for review, then commit after approval. | | clean-code | General code quality | Any task writes or modifies code and should stay clear, simple, focused, and readable. | | typescript | TypeScript guidance | A task changes .ts or .tsx files and needs practical TypeScript discipline. | | command-pattern | Vertical-slice command design | Work involves command handlers, workflows, request processing, or executable tasks. | | ai-prompt-engineer-master | Prompt and template quality | You are creating, rewriting, compressing, or evaluating prompts or reusable AI instructions. | | sibu-template-change | Sibu template maintenance | You change files under templates/ or template manifest metadata and need safe lifecycle validation. |

The point is not to make agents magical. The point is to give them the right job, the right context, and a tight enough boundary that a human can trust the result.

Advanced setup: MCP servers

Sibu can generate MCP server configuration for supported agents. Supported MCP servers include GitHub and Notion.

Sibu only writes and tracks MCP config files. Runtime prerequisites, credentials, provider authentication, workspace access, and provider permissions remain user-owned.

Confirm available MCP servers

From a Sibu-managed project, run:

sibu mcp list

This shows each available MCP server and whether it is already selected for the project.

Configure the GitHub MCP server

You can select GitHub during sibu init, or add it later:

sibu mcp use github

Sibu writes the relevant config for the agents selected in the project:

• Codex: .codex/config.toml
• Claude: .mcp.json
• Gemini: .gemini/settings.json

All supported agents use GitHub's hosted MCP endpoint instead of requiring Docker. Codex uses Codex's native bearer-token environment variable setting:

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PERSONAL_ACCESS_TOKEN"

Claude uses HTTP MCP config with an authorization header:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Gemini uses streamable HTTP config with an authorization header:

{
  "mcpServers": {
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

Create a GitHub personal access token with the repository permissions your agent should have, then expose it before launching the agent:

export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

Do not commit tokens or write them into Sibu-managed config files. The generated configs read GITHUB_PERSONAL_ACCESS_TOKEN from the environment so credentials can stay outside the repository.

Configure the Notion MCP server

You can select Notion during sibu init, or add it later:

sibu mcp use notion

When Notion is selected, Sibu asks for a Notion docs destination parent page URL or page ID. Sibu stores that parent page reference in .sibu/state.json so feature-doc export guidance knows where Notion pages should go.

Sibu configures supported agent MCP files for Notion, but it does not manage Notion OAuth login, workspace selection, integration installation, page permissions, credentials, or live connectivity. Your Notion MCP connection must be authenticated separately and must have access to the configured parent page. For provider setup details, use Notion's MCP documentation: https://developers.notion.com/guides/mcp/get-started-with-mcp.

Feature briefs, technical designs, and UX docs are still written to local Markdown first. Notion is an optional export destination, not Sibu's source of truth.

For Codex with the hosted Notion MCP server, you may need to run the agent-specific MCP login flow after Sibu writes config, such as:

codex mcp login notion

Stop managing an MCP server

To remove a selected MCP server from Sibu's state, run:

sibu mcp stop github
sibu mcp stop notion

Sibu updates generated agent config where possible and asks whether to keep or delete MCP-only config files. Stopping Notion only updates local Sibu state and managed MCP config files; it does not delete Notion pages or change Notion permissions.

Contributing

Contributor guidance lives near the bottom on purpose: the README is mostly for people deciding whether to try Sibu. If you are here to work on Sibu itself, this is the quick path.

The CLI entrypoint lives in src/entrypoints/cli/, command handlers live in src/features/, shared workflow utilities live in src/shared/, and everything compiles to bin/sibu.js. The bin/ directory is generated by pnpm build and should not be edited directly.

Local setup

pnpm install
pnpm build
pnpm check
pnpm test
pnpm verify

pnpm verify is the normal local confidence check: it builds, typechecks, and runs tests.

Local CLI testing

Use pnpm dev:link to make the local sibu command available from any directory while developing:

pnpm dev:link

Then test it in a scratch project:

mkdir /tmp/test-sibu-project
cd /tmp/test-sibu-project
git init
sibu init
sibu doctor
sibu sync
sibu skills list
find . -maxdepth 2 -type f | sort

After editing CLI source files under src/, rebuild before testing again:

cd path/to/ai-augmented-workflow
pnpm build

When you are done testing the linked CLI, remove the global link:

pnpm dev:unlink

This linked workflow is useful for day-to-day contributor development, but it is not a supported end-user install path and it is not the release-readiness check for npm publishing.

Package validation

Before treating a build as ready to publish, validate the packaged artifact instead of relying only on local package linking:

pnpm verify
pnpm run validate:packed-runtime

For deeper release-readiness validation, run:

pnpm run validate:release

The packed-runtime validation installs the produced tarball into an isolated npm prefix, verifies sibu --help, creates a fixture project, and runs sibu doctor to prove the installed CLI can read bundled runtime assets such as templates.

If you need to inspect tarball contents manually:

mkdir -p /tmp/sibu-pack
npm pack --json --pack-destination /tmp/sibu-pack
tar -tzf /tmp/sibu-pack/juancr11-sibu-*.tgz | sort

Expected runtime package contents include:

• bin/sibu.js
• runtime code under bin/entrypoints/, bin/features/, and bin/shared/
• templates/
• README.md

Release notes and releases

For release workflow details, use docs/releasing.md. That guide covers version bumping, CHANGELOG.md, tarball-based validation, npm publish, GitHub Release creation, and post-publish verification.

At a high level, every Sibu release should update both release-note surfaces:

• CHANGELOG.md as the canonical source in the repo
• the matching GitHub Release as the public release surface

Focused validation helpers

Use deterministic override hooks to validate doctor version-advisory behavior without depending on a real npm publish cycle:

pnpm run validate:doctor-version-advisory

This proves both of these cases locally:

• a newer npm version is available and sibu doctor suggests npm install -g @juancr11/sibu
• npm lookup is unavailable and sibu doctor still completes the local health check without failing

For one-off manual checks, you can also run:

SIBU_NPM_LATEST_VERSION=9.9.9 node ./bin/sibu.js doctor
SIBU_NPM_LOOKUP_MODE=offline node ./bin/sibu.js doctor

Use the local two-tarball validation flow to prove that upgrading Sibu can surface new drift without changing project files automatically:

pnpm run validate:post-update-doctor-drift

Changing templates

Templates are versioned product artifacts. When changing any file under templates/, use the local template-change skill if available and update templates/manifest.json in the same change.

Template change checklist:

• Bump the global templateVersion when any template changes.
• Bump each changed template's own version.
• Add user-facing change notes that explain what changed and why it matters.
• Avoid renaming template paths unless migration or backwards compatibility is handled.
• Run pnpm verify.
• Test sibu init, sibu doctor, and sibu sync in a temporary project when practical.

The changes entries in templates/manifest.json are shown by sibu sync, so write them for users rather than as code-level diff notes. If using an AI coding agent, explicitly ask it to use the local template-change skill before editing templates.