sisyo

Smart documentation system for vibe coding with Claude Code. Docs auto-update as you build. Token-efficient 3-level routing pattern.

Install

npx sisyo

Run it in your project root.

What it creates

your-project/
  SISYO.md                             # Project rules (imported by CLAUDE.md)
  CLAUDE.md                            # Auto-created or updated with @SISYO.md
  .claude/
    rules/docs.md                      # Doc rules (auto-loaded)
    skills/vibe-docs/SKILL.md          # Brain (loaded on trigger)
  docs/
    MAP.md                             # Level 1: routing table
    99_progress/todo.md                # Task backlog
    99_progress/handoff.md             # Session recovery
    99_progress/features.md            # Feature log

SISYO.md holds the project config. CLAUDE.md is untouched if it already exists — sisyo just appends @SISYO.md to it.

How it works

Problem: Loading all docs into context = 20K+ tokens = runs out fast.

Solution: 3-level routing -- load only what you need, when you need it.

Level 1: MAP.md              (~500 tokens)  Read ALWAYS
    |
Level 2: folder/_summary.md  (~200 tokens)  Compact table of all items
    |
Level 3: folder/[detail].md                 Full detail, ONLY when needed

Most tasks only need Level 1 + Level 2. Detail files load only when actively modifying.

Example flow

MAP.md
  "03_database -- 4 tables: users, posts, comments, categories"
    |
    v
03_database/_summary.md
  | Table    | Description              | Key relations |
  | users    | Accounts, auth, profile  | --            |
  | posts    | Blog posts, draft/publish| -> users      |
    |
    v  (only if modifying users table)
03_database/users.md
  Full column definitions, indexes, constraints

Auto-triggers

The vibe-docs skill triggers automatically when you:

• Complete a feature -> logs to 99_progress/features.md
• Design database tables -> updates 03_database/_summary.md + detail file
• Add API endpoints -> updates 04_api/_summary.md + detail file
• Plan features -> updates 01_requirements/_summary.md + detail file
• Make architecture decisions -> updates 02_architecture/decisions.md
• Set up auth/security -> creates 08_security/[topic].md
• Integrate third-party service -> creates 09_integrations/[service].md
• Complete any task -> updates 99_progress/todo.md
• End a session -> writes 99_progress/handoff.md

Every change updates bottom-up: detail → _summary.md → MAP.md

Session recovery

After /clear or starting fresh:

Read handoff and continue

Claude reads MAP.md + handoff.md + todo.md (~3K tokens) and picks up where you left off.

Update

npx sisyo --update              # update managed files, keep everything you edited
npx sisyo --update --dry-run    # show what would change, write nothing
npx sisyo --update --force      # also overwrite managed files you edited locally

sisyo splits files into two groups so frequent updates never clobber your work:

| Group | Files | On --update | |---|---|---| | Managed (sisyo-owned) | .claude/rules/docs.md, .claude/skills/* | Replaced only if your copy is byte-identical to what sisyo last installed. New skills are added. Skills sisyo dropped are removed only if untouched. | | Yours | SISYO.md, CLAUDE.md, docs/** | Never touched. Missing files are created once. |

Hashes of every managed file are recorded in .claude/sisyo.json (commit it). If you edited a managed file, --update keeps your version and writes the new one next to it as <file>.sisyo-new (gitignored) so you can diff and decide:

git diff --no-index .claude/skills/vibe-docs/SKILL.md .claude/skills/vibe-docs/SKILL.md.sisyo-new

Move the .sisyo-new file over the original to accept, delete it to keep yours, or rerun with --force to accept all.

Tip: put project-specific rules in SISYO.md or your own .claude/rules/<topic>.md rather than editing a shipped skill — those files are yours and update-proof.

Doc folders

| Folder | Purpose | |---|---| | 00_schedule/ | Roadmap, milestones, sprint plans | | 01_requirements/ | Feature specs, user stories | | 02_architecture/ | System design, tech decisions (ADR) | | 03_database/ | Schema, ERD, migration log | | 04_api/ | API endpoint specs by module | | 05_frontend/ | Pages, components, routing | | 06_infra/ | Deploy, Docker, CI/CD, env vars | | 07_testing/ | Test plans, test cases, edge cases | | 08_security/ | Auth flows, permissions, API keys | | 09_integrations/ | Third-party services config & usage | | 99_progress/ | Feature log, TODO, session handoff |

Each folder with multiple items has a _summary.md (compact table) + detail files. Folders are created on-demand. No empty placeholders.

Skills

Optional best-practice guides that Claude loads on demand:

| Skill | Triggers on | |---|---| | vibe-docs | Doc updates, feature changes, session end | | html-docs | Generate polished HTML docs (Tailwind, colorful, rounded modern) for devs/users | | terraform-best-practices | Terraform/AWS: never auto-apply, cost confirm, plan summary, module layout, IAM/SGR/secrets rules | | fastapi-best-practices | FastAPI backends, REST APIs, Python web services | | react-page-oriented | React/Next.js pages, component structure | | gemini-integration | Google Gemini API: model roles via config keys, 3.x request rules, streaming chat + tools, Live voice (ephemeral token, gemini-3.8-live async tools / 3.1 sync), structured tool results, embeddings/rerank, JSON mode, grounding, PDF, TTS, troubleshooting | | neon-game-ui-ux-skill | Neon, game-like UI/UX design system (React + Tailwind + motion), guidance only: tokens, component anatomy, HUD (level, XP, streak, daily goal), bottom bar with a centre progress dial + radial menu, gamification patterns (XP, quests, daily path, rewards), duotone icons on an open-source base, motion and accessibility rules |

After install

1. Edit SISYO.md — replace [Project Name] with yours
2. Open Claude Code and start building
3. Docs update automatically as you work

Author

HoangThang - blog.thangchiba.com

License

MIT