{
  "markdown": "# Reef\n\nMost codebase knowledge lives in someone's head, or gets re-derived from scratch every time someone asks a question. Reef takes a different approach: it builds a persistent, structured wiki from your source code — one that compounds over time instead of being rediscovered on every query.\n\nReef is a Claude Code plugin. It reads source code, asks the right questions, and produces interlinked markdown artifacts with YAML frontmatter, source citations, and honest gap tracking. The AI does the reading and the bookkeeping. You bring the domain knowledge and decide what matters. Output is Obsidian-native, local-first, plain markdown.\n\n## Built For\n\nReef is designed for **codebases that have services, data, and interfaces**. If your code has APIs (REST, gRPC, GraphQL), persistent data (any database or ORM), and components that talk to each other — Reef will produce rich, interlinked artifacts.\n\nIt works well for: microservices, monoliths with modules, full-stack apps, data pipelines, infrastructure-as-code, DevOps toolchains, and anything in between.\n\nIt is not the right tool for: native mobile apps with no backend, game engines, embedded firmware, or ML training notebooks. These don't have the data schemas, API surfaces, or service boundaries that Reef is built to document.\n\n## Guide\n\nFor a full step-by-step walkthrough of the workflow (init → scuba → deep → update), see **[docs/guide.md](docs/guide.md)**.\n\n## Quick Start\n\n```\n/plugin marketplace add eunji-jessi-jung/reef\n/plugin install reef@eunji-jessi-jung-reef\n```\n\nThen, in any project directory:\n\n```\n/reef:init        # Set up the reef, then auto-runs snorkel + source in parallel:\n                  #   snorkel — auto-discover 3-6 draft artifacts\n                  #   source  — extract full API specs and ERDs\n/reef:scuba       # Deepen drafts through guided Socratic questioning\n```\n\n## Skills\n\n| Skill | Description |\n|-------|-------------|\n| `/reef:init` | Bootstrap a new reef — scope, scaffold, index, seed questions |\n| `/reef:snorkel` | Auto-discovery surface pass, 3-6 draft artifacts, no questions asked |\n| `/reef:source` | Extract full API specs and ERDs with tiered protocol + recipe caching |\n| `/reef:scuba` | Socratic deepening through guided question-and-answer |\n| `/reef:deep` | Exhaustive line-by-line tracing of critical areas |\n| `/reef:artifact` | Explore a topic, capture knowledge, or update an artifact |\n| `/reef:update` | Pull sources, detect changes, generate update report for review |\n| `/reef:lint` | Lint artifacts for format and structural errors, with auto-fix |\n| `/reef:health` | Read-only validation and freshness report |\n| `/reef:feed` | Scan for new context files and connect them to the reef |\n| `/reef:test` | Test whether the reef answers your real questions |\n\n## When to Use Each Depth\n\n**Snorkel** — First contact with a codebase. No questions, no input. Produces draft artifacts with honest `known_unknowns`. Also useful when adding a new source to an existing reef.\n\n**Source** — After snorkel, before scuba. Extracts complete API specs and entity-relationship diagrams from your source repos. Tries copying existing specs first, then runtime extraction, then code reading as fallback. Caches successful recipes so repeat runs are fast.\n\n**Scuba** — You have drafts, full API/ERD specs, and domain knowledge. The AI reads code and asks you things code alone can't answer: why decisions were made, who owns what, what breaks in practice. This is where most real knowledge gets captured.\n\n**Deep** — Critical systems where shallow reading misses real behavior. Line-by-line tracing, 5+ Key Facts per artifact with precise citations. Reserve for areas where getting it wrong has consequences.\n\n## I Built a Reef — Now What?\n\nA reef is a living knowledge base. Once scuba completes (even partially), you can:\n\n- **Feed it to dev agents** — point Claude Code, Cursor, or Copilot at the reef directory as context so they understand your domain, not just your syntax\n- **Onboard teammates** — open in Obsidian, explore the knowledge graph, ramp up without scheduling walkthrough meetings\n- **Export as docs** — artifacts are structured markdown with frontmatter; copy into Confluence, Notion, or a static site\n- **Audit and review** — `/reef:health` for coverage gaps, `/reef:test` to check if the reef answers your real questions\n- **Keep it alive** — `/reef:update` after code changes; each update costs a fraction of the initial build\n\nSee [docs/guide.md](docs/guide.md) for the full workflow.\n\n## Domain Boundaries\n\nOne reef covers one ecosystem — services that talk to each other. The sweet spot is **3-15 repos** that form a coherent domain. This is where Reef delivers the most value: complex enough that no one person holds the full picture, small enough that Reef can trace every cross-system connection.\n\n- **1-2 repos:** Reef works, but the code might be its own best documentation. Consider whether you need it.\n- **3-15 repos:** The goldilocks zone. Cross-service contracts, shared entities, and auth boundaries are where the real knowledge lives — and where it gets lost most often.\n- **15+ repos:** Split into multiple reefs by team or domain. Each reef should cover services that directly interact. Services that don't talk to each other belong in separate reefs.\n\nIn a large org (hundreds of repos), the right unit is one reef per team or domain — not one reef for the whole org. A platform team's reef and a product team's reef are separate, each covering their own ecosystem.\n\n## The Question Bank\n\nSeed questions during `/reef:init`. These are the north star. `/reef:test` evaluates whether the reef actually answers them. A reef that answers 8 of 10 questions is useful. A reef with beautiful artifacts that answers 2 of 10 is decorative.\n\n## Keeping It Alive\n\nKnowledge bases die when the maintenance burden outgrows the value. Reef shifts that burden to the machine. `/reef:update` re-indexes sources, detects changes, and walks you through updating affected artifacts. `/reef:health` reports the state without modifying anything. Artifacts don't flip from good to bad — they age gradually. Run these after significant code changes.\n\n## Nine Artifact Types\n\n| Type | Prefix | Question it answers |\n|------|--------|-------------------|\n| System | SYS- | What does this service do? |\n| Schema | SCH- | What does this data mean? |\n| API | API- | What can I call? |\n| Process | PROC- | What happens when...? |\n| Decision | DEC- | Why was it built this way? |\n| Glossary | GLOSSARY- | What does this term mean? |\n| Contract | CON- | What do these systems agree on? |\n| Risk | RISK- | What could go wrong? |\n| Pattern | PAT- | What problem does this solve repeatedly? |\n\n## Obsidian\n\nArtifacts are wikilinked with `[[artifact-id]]` syntax — open the reef directory as an Obsidian vault to see the full graph of how everything connects. Enable Graph View and Dataview plugins for the best experience. The reef is plain markdown, so any markdown tool works.\n\n## Adding Your Own Docs\n\nHave architecture docs, design specs, or runbooks that aren't in the codebase? Drop them into `sources/raw/` in your reef directory. Scuba will pick them up when deepening artifacts — they're especially useful for answering questions that code alone can't.\n\n## See It in Action\n\n**[supabase-reef](https://github.com/eunji-jessi-jung/supabase-reef)** — a complete reef covering 5 Supabase repos (Go, Elixir, TypeScript, React) built by a PM with zero Supabase knowledge. Includes a [benchmark report](https://github.com/eunji-jessi-jung/supabase-reef/blob/main/reef-benchmark-report.md) testing whether the reef actually helps AI agents (28 runs, 2 models, 7 tasks, with honest caveats).\n\n## Author\n\n**Eunji Jung** — Product Manager building tools for AI-assisted software engineering.\n\n- [LinkedIn](https://www.linkedin.com/in/eunji-jessi-jung/)\n- Questions or feedback? [Open an issue](https://github.com/eunji-jessi-jung/reef/issues)\n",
  "bytes": 7963,
  "sha": "e1dd575f3fc285d23525399c1d67632cb748564eb18a4a9f6314008729c3d425",
  "repo_slug": "eunji-jessi-jung/reef",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_eunji_jessi_jung_reef_reef_1aa02de1/readme"
}