@juancr11/sibu 0.12.2 → 0.12.3

package/README.md

@@ -1,54 +1,200 @@
-# ai-augmented-workflow
+# Sibu
 
-A local workspace for developing and refining an AI-augmented software development workflow.
+Sibu helps developers set up and maintain an AI-augmented development workflow without handing the steering wheel to the machine.
 
-## Install Sibu
+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.
 
-The official way to install and update Sibu is with npm:
+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:
 
 ```sh
 npm install -g @juancr11/sibu
 ```
 
-After installing, the normal user flow is:
+Then run the normal first-use flow from the project you want to equip with an AI workflow:
+
+```sh
+sibu init
+sibu doctor
+sibu sync
+```
+
+What happens:
 
-1. run `sibu init` in your project
-2. run `sibu doctor` to check workflow health
-3. if `sibu doctor` says a newer npm version exists, run `npm install -g @juancr11/sibu`
-4. rerun `sibu doctor`
-5. if drift is reported, decide whether to run `sibu sync`
+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 Sibu alone does not change project files. It only changes what `sibu doctor` can detect against the newer installed templates.
+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.
 
-## CLI
+## Core commands
 
-Sibu helps projects adopt and maintain AI workflow support files safely.
+### `sibu init`
 
-From a project directory, run:
+Run this once in a project to adopt Sibu:
 
 ```sh
 sibu init
 ```
 
-`sibu init` is idempotent: it opens a polished interactive flow, lets you select supported agents with the keyboard, creates missing workflow files for that selection, keeps existing files unchanged, and reports when no changes are needed. When `AGENTS.md` is missing, the CLI asks for a project overview and writes the file based on the template in this repository. It can also create Codex, Gemini, and Claude support files when selected. Sibu records the generated workflow state in `.sibu/state.json` so `sibu doctor` can detect drift safely.
+`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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+sibu skills list
+```
+
+Stop managing a selected skill file when it no longer fits the project:
+
+```sh
+sibu skills stop <file>
+```
+
+Sibu updates state, removes the selected skill when applicable, and asks whether to keep or delete the local file.
 
-Use `sibu doctor` to run a read-only health check. It reports missing managed files, local modifications, malformed state metadata, and template version drift without changing files.
+### `sibu mcp`
 
-If `sibu doctor` tells you that a newer npm version exists, update with `npm install -g @juancr11/sibu`, rerun `sibu doctor`, and only then decide whether to run `sibu sync`. Updating Sibu alone changes what doctor can detect; it does not change project files.
+List, add, or stop supported MCP server configuration:
 
-Use `sibu sync` to review template updates interactively. It explains human-readable template changes, protects local edits from automatic overwrites, and lets you apply safe updates, mark customized files as reviewed, write side templates, stop managing a file, or skip for later. Sibu records each file as `managed`, `customized`, or `unmanaged` in `.sibu/state.json`.
+```sh
+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.
+
+```mermaid
+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.
 
-Use `sibu skills list` to list available workflow skills and see which selectable skills are currently enabled for the project.
+## Skills Inventory
 
-Use `sibu skills stop <file>` to stop managing an Sibu-tracked workflow file. The file is marked as `unmanaged` in `.sibu/state.json`, removed from the selected skill state when applicable, and the CLI asks whether to keep or delete the local file.
+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.
 
-## MCP server setup
+```mermaid
+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, and provider authentication remain user-owned.
+Sibu only writes and tracks MCP config files. Runtime prerequisites, credentials, provider authentication, workspace access, and provider permissions remain user-owned.
 
-### 1. Confirm available MCP servers
+### Confirm available MCP servers
 
 From a Sibu-managed project, run:
 
@@ -58,7 +204,7 @@ sibu mcp list
 
 This shows each available MCP server and whether it is already selected for the project.
 
-### 2. Configure the GitHub MCP server
+### Configure the GitHub MCP server
 
 You can select GitHub during `sibu init`, or add it later:
 
@@ -111,9 +257,7 @@ Gemini uses streamable HTTP config with an authorization header:
 }
 ```
 
-### 3. Provide GitHub credentials
-
-Create a GitHub personal access token with the repository permissions your agent should have, then expose it as an environment variable before launching the agent:
+Create a GitHub personal access token with the repository permissions your agent should have, then expose it before launching the agent:
 
 ```sh
 export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
@@ -121,7 +265,7 @@ 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.
 
-### 4. Configure the Notion MCP server
+### Configure the Notion MCP server
 
 You can select Notion during `sibu init`, or add it later:
 
@@ -141,7 +285,7 @@ For Codex with the hosted Notion MCP server, you may need to run the agent-speci
 codex mcp login notion
 ```
 
-### 5. Stop managing an MCP server
+### Stop managing an MCP server
 
 To remove a selected MCP server from Sibu's state, run:
 
@@ -152,45 +296,33 @@ 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.
 
-## Release notes and changelog
-
-For every Sibu release, update both release-note locations:
-
-- `CHANGELOG.md` is the canonical source in the repo
-- the matching GitHub Release is the public release surface
-
-When preparing a release, write or update the `CHANGELOG.md` entry first, then publish the matching GitHub Release using that same summary.
-
-This keeps one source of truth in the repo while still giving users a public release page they can browse from GitHub.
-
-## Maintainer release workflow
+## Contributing
 
-If you are preparing a new Sibu npm release, use [`docs/releasing.md`](docs/releasing.md). That guide covers version bumping, `CHANGELOG.md`, tarball-based validation, npm publish, GitHub Release creation, and post-publish verification.
-
-## Contributor development
-
-The rest of this README section is for contributors working on Sibu itself, not for end users installing the CLI.
+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
+
 ```sh
 pnpm install
+pnpm build
+pnpm check
+pnpm test
 pnpm verify
 ```
 
-## Contributor local testing
-
-Use `pnpm link --global` to make the local `sibu` command available from any directory while developing.
+`pnpm verify` is the normal local confidence check: it builds, typechecks, and runs tests.
 
-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. For release readiness, prefer tarball-based validation with `npm pack` so you verify the exact package contents users will install.
+### Local CLI testing
 
-From this repository:
+Use `pnpm dev:link` to make the local `sibu` command available from any directory while developing:
 
 ```sh
 pnpm dev:link
 ```
 
-Then test it in a new project directory:
+Then test it in a scratch project:
 
 ```sh
 mkdir /tmp/test-sibu-project
@@ -206,7 +338,7 @@ find . -maxdepth 2 -type f | sort
 After editing CLI source files under `src/`, rebuild before testing again:
 
 ```sh
-cd /home/juanca/code/ai-augmented-workflow
+cd path/to/ai-augmented-workflow
 pnpm build
 ```
 
@@ -216,55 +348,58 @@ When you are done testing the linked CLI, remove the global link:
 pnpm dev:unlink
 ```
 
-## Validate the npm package
+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.
 
-Before treating a build as ready to publish, validate the packaged artifact instead of relying only on `pnpm link`.
+### Package validation
 
-### 1. Inspect the tarball contents
+Before treating a build as ready to publish, validate the packaged artifact instead of relying only on local package linking:
 
 ```sh
 pnpm verify
+pnpm run validate:packed-runtime
+```
+
+For deeper release-readiness validation, run:
+
+```sh
+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:
+
+```sh
 mkdir -p /tmp/sibu-pack
 npm pack --json --pack-destination /tmp/sibu-pack
 tar -tzf /tmp/sibu-pack/juancr11-sibu-*.tgz | sort
 ```
 
-Use the tarball listing to confirm the packed artifact includes the expected runtime files:
+Expected runtime package contents include:
 
 - `bin/sibu.js`
 - runtime code under `bin/entrypoints/`, `bin/features/`, and `bin/shared/`
 - `templates/`
 - `README.md`
 
-This check proves the package contents are correct, but it does **not** prove the installed CLI runs correctly after npm global install.
-
-### 2. Smoke test the installed tarball runtime
-
-```sh
-pnpm run validate:packed-runtime
-```
-
-This command:
+### Release notes and releases
 
-- runs `npm pack` in an isolated temporary workspace
-- installs the produced tarball into an isolated npm prefix
-- verifies `sibu --help` runs from the installed binary
-- creates a temporary fixture project outside this repo
-- runs `sibu doctor` in that fixture project to prove the installed CLI can read bundled runtime assets such as templates
+For release workflow details, use [`docs/releasing.md`](docs/releasing.md). That guide covers version bumping, `CHANGELOG.md`, tarball-based validation, npm publish, GitHub Release creation, and post-publish verification.
 
-If this command fails, treat it as an installed-package runtime problem rather than a normal local-development issue.
+At a high level, every Sibu release should update both release-note surfaces:
 
-Treat tarball inspection plus `pnpm run validate:packed-runtime` as the release-readiness path for npm packaging changes. Use `pnpm dev:link` only for interactive local development.
+- `CHANGELOG.md` as the canonical source in the repo
+- the matching GitHub Release as the public release surface
 
-## Validate the doctor npm update advisory
+### Focused validation helpers
 
-Use the deterministic override hooks to verify both advisory scenarios without depending on a real npm publish cycle:
+Use deterministic override hooks to validate doctor version-advisory behavior without depending on a real npm publish cycle:
 
 ```sh
 pnpm run validate:doctor-version-advisory
 ```
 
-This validation proves both of these cases locally:
+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
@@ -276,23 +411,13 @@ SIBU_NPM_LATEST_VERSION=9.9.9 node ./bin/sibu.js doctor
 SIBU_NPM_LOOKUP_MODE=offline node ./bin/sibu.js doctor
 ```
 
-## Validate post-update drift after upgrading Sibu
-
 Use the local two-tarball validation flow to prove that upgrading Sibu can surface new drift without changing project files automatically:
 
 ```sh
 pnpm run validate:post-update-doctor-drift
 ```
 
-This validation proves the full explicit flow locally:
-
-- install an older local tarball
-- run `sibu doctor` and see the npm update advisory
-- update to a newer local tarball
-- rerun `sibu doctor` and see drift reported
-- confirm no files change until `sibu sync` is explicitly run
-
-## Changing templates
+### 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juancr11/sibu",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "CLI for setting up a local AI-augmented development workflow.",
   "repository": {
     "type": "git",