Codewiki

CodeWiki — Product Knowledge Base Generator

Scan code, fetch product context, discover user flows, and generate a structured codewiki/ knowledge base.

Output templates are in this skill's templates/ directory. Read each template only when generating that specific file — do NOT load all templates at once.

HARD RULES

1. Phase 1 is not optional. Product context is the difference between a useful wiki and a mechanical code listing. Complete it before scanning. If user can't answer, use the code-first fallback.
2. Multi-repo workspace must be verified before scanning. If repos aren't in a shared parent folder, stop and help the user set it up.
3. Never scan all repos simultaneously. Use Scan → Write to _scratch/ → Carry 30-line summary → Next. This is how you survive large multi-repo projects.
4. Never skip a service in microservices. User flows that touch 5 services are useless if one is undocumented. Every service gets at least a lightweight scan.
5. Scan in priority order. Infrastructure/contracts → gateway → frontends → core business services → supporting services.
6. Report progress between repos. Tell the user what you found and which repo is next. Do not ask for permission between repos — just continue. Only pause on errors or contradictions.
7. On startup, check if codewiki/_scratch/ exists. If it does, offer to resume from previous scan data.
8. Always use codewiki/ (no dot prefix). Ensures visibility in file explorers and default git tracking.
9. Adaptive detection. If hardcoded grep patterns don't match anything for a component, read the entry point file and trace outward. Don't report "no endpoints found" without trying alternative approaches.
10. WebFetch failures. Report the specific error (401, 404, timeout) and continue. Never silently skip a URL.

---

Phase 1: Product Context Gathering (MANDATORY — DO NOT SKIP)

> STOP. You MUST complete Phase 1 before scanning any code. > Do not run ls, grep, or read any files until Phase 1 is done. > If the user says "just scan the code" or tries to skip, explain that > the wiki quality depends heavily on product context and ask them to > answer at least questions 1–3 before proceeding.

Step 1a: Ask the User

Ask all of these in a single message. Mark which are required vs. optional:

1. Product name (required) — What is this product called?
2. One-liner (required) — Describe it in one sentence. What does it do and for whom?
3. Target users (required) — Who uses this? (e.g., developers, marketers, internal ops team)
4. Product URLs (optional but strongly recommended) — Provide any of:

• Marketing website / landing page
• Documentation site
• API docs URL
• App Store / Play Store listing
• README or repo URL (if different from the working directory)

1. Repo list (required for multi-repo) — If this is a multi-repo product:

• List all repos (backend, frontend, mobile app, comms, infra, etc.)
• Are they all cloned into a single parent folder? If not, I'll ask you to set that up.
• Provide git clone URLs for any not yet cloned.

1. Anything the code won't tell me? (optional) — Business context, upcoming changes, non-obvious terminology, areas of tech debt, inter-service communication patterns, etc.

Code-first fallback: If user says they can't answer 1–3, say: "No problem — I'll scan the code first and come back with my best guess for you to correct." Infer product name from package.json name field or README title, one-liner from package.json description or README first paragraph, users from UI/API patterns (admin dashboard = internal ops, public signup = consumers, API-only = developers). Present guesses for confirmation before continuing to Phase 2.

Step 1b: Multi-Repo Workspace Setup

> For multi-repo products, all repos MUST be cloned into a single parent folder. > This is how CodeWiki discovers cross-repo relationships.

Expected structure:

/              ← master folder
├── backend/                 ← git clone 
├── frontend/                ← git clone 
├── mobile-app/              ← git clone 
├── comms-service/           ← git clone 
├── shared-libs/             ← git clone 
└── infra/                   ← git clone 

If repos are not yet organized this way, give the user exact commands:

mkdir -p ~/projects/ && cd ~/projects/
git clone  
git clone  
# ... etc

Then ask the user to cd into the master folder and run CodeWiki from there.

Verify the setup:

ls -la
for dir in */; do echo "$dir: $(git -C "$dir" remote get-url origin 2>/dev/null || echo 'not a git repo')"; done

If any repos are missing, tell the user which ones and provide the clone command. Do NOT proceed to Phase 2 until the workspace is verified.

Step 1c: Fetch External Context

For each URL provided, use WebFetch to extract product context.

Error handling: If a URL fails (auth wall, 404, timeout), tell the user which URL failed and why, then continue with the rest. Do not silently skip.

For each successful fetch, extract:

• Landing page copy, feature descriptions, value propositions
• App store descriptions and key metadata
• Documentation structure (table of contents, section names)
• API documentation overview (auth method, base URL, resource groups)

Step 1d: Summarize Before Proceeding

Present a short summary back to the user: > "Here's what I understand about [Product Name] before I look at the code: ..."

Ask: "Is this accurate? Anything to correct or add?"

Only after the user confirms, proceed to Phase 2.

After confirmation, estimate scope: > "Based on [N repos/components], this will take [several phases]. I'll report progress after each repo/component."

---

Context Window Management (Multi-Repo Strategy)

> CRITICAL: Do NOT scan all repos at once. Scanning multiple repos simultaneously > will exhaust the context window. Instead, use the Scan → Summarize → Flush → Next > pattern described below.

Scan Priority Order

Scan in this order. The goal is top-down: infrastructure first (the "map"), then entry points, then services behind them.

Priority 1 — Infrastructure & contracts (scan first)

• infra/, deploy/, platform/ — docker-compose, k8s manifests, terraform
• Shared proto/OpenAPI/AsyncAPI specs
• Shared libraries / type packages

Why first: Gives you the full service map, ports, dependencies, and contracts before any individual service. It's the table of contents.

Priority 2 — API gateway / BFF (Backend-for-Frontend)

• The service that receives external traffic and routes it internally
• Often named: gateway, api-gateway, bff, proxy

Why second: Shows all user-facing endpoints and which internal service handles each one.

Priority 3 — Frontend(s)

• Web frontend, mobile app, admin dashboard
• Scan routes/screens, API client configuration, state management

Why third: Now you can map screens → gateway endpoints → internal services.

Priority 4 — Core business services

• Services that own primary business data (users, orders, payments, etc.)
• Prioritize by: how many user flows touch this service

Priority 5 — Supporting services

• Notifications, analytics, logging, search, file storage
• These are consumed by other services but rarely initiate flows

The Scan → Summarize → Flush → Next Pattern

For each repo/service, follow this cycle:

1. SCAN      Read the repo: tech stack, endpoints, models, events, env vars
2. WRITE     Write findings to codewiki/_scratch/.md (on disk)
3. SUMMARIZE Create a compact summary (max 30 lines) of:
             - What this service does (1-2 sentences)
             - Endpoints it exposes (list)
             - Events it produces/consumes (list)
             - Data models it owns (list)
             - How it connects to other services (list)
4. CARRY     Keep ONLY the compact summary in working memory
5. NEXT      Move to the next repo — raw scan data is on disk, not in context

The _scratch/ folder:

codewiki/
├── _scratch/                  ← temporary, per-repo scan notes
│   ├── backend.md
│   ├── frontend.md
│   ├── comms-service.md
│   └── ...
├── overview.md                ← final output files (generated in Phase 5)
├── architecture.md
└── ...

Compact summary format (carried between repo scans):

##  |  | 
Purpose: 
Endpoints: GET /users, POST /users, GET /users/:id, ...
Produces: user.created, user.updated
Consumes: payment.completed
Models: User, Role, Session
Calls: payment-service (gRPC), notification-service (HTTP)
DB: postgres (users, roles, sessions tables)

Progress Reporting

After scanning each repo, tell the user: > "✓ Scanned backend (3/6 repos done). Found 14 endpoints, 3 event topics, 5 models. > Next up: comms-service. Continuing..."

Do NOT ask for permission between each repo — just report progress and continue.

---

Phase 2: Codebase Analysis

Step 2a: Project Layout & Scoping

Single-repo projects:

ls -la
find . -maxdepth 2 -type f -name "*.json" -o -name "*.toml" -o -name "*.yaml" -o -name "*.yml" -o -name "*.mod" -o -name "*.lock" | head -50

Multi-repo master folder:

ls -la
for dir in */; do
  echo "=== $dir ==="
  ls "$dir"/*.json "$dir"/*.toml "$dir"/*.yaml "$dir"/*.yml "$dir"/*.mod "$dir"/Dockerfile 2>/dev/null
  echo ""
done

Identify:

• Single repo: Project type (monorepo, single app, library, CLI tool, etc.)
• Multi-repo: Map each folder to its role (backend, frontend, mobile, comms, infra, shared libs, etc.)

For multi-repo, present the inventory: > "I found [N] repos in this workspace: > | Folder | Likely role | Stack signals | > |--------|------------|---------------| > | backend/ | API server | go.mod, Dockerfile | > | frontend/ | Web app | package.json (next), tsconfig.json | > | ... > > I'll scan them in this order: [list in priority order]. Starting now."

Architecture Classification

Classify the project:

• Single app — one deployable unit (e.g., a Rails app, a Next.js full-stack app)
• Modular monolith — one deployable unit with clearly separated internal modules
• Microservices — multiple independently deployable services
• Monorepo with shared packages — multiple apps/services sharing code via a package manager workspace

Detection signals for microservices:

• docker-compose.yml defining multiple services with separate build contexts
• Multiple directories each with their own Dockerfile
• Multiple directories each with their own dependency files (separate go.mod, package.json, requirements.txt)
• Presence of API gateway, service mesh config, or message broker config
• Proto/OpenAPI/AsyncAPI spec files defining service contracts
• Kubernetes manifests or Helm charts with multiple deployments

State your classification to the user before proceeding.

Scoping Gate

If microservices or multi-service architecture: Do NOT ask the user to skip services. Instead, use a two-tier scan:

> "This is a microservices project with [N] services. I found: [list them]. > I'll do a lightweight scan of all services first to map the full topology, > then a deep scan of the [3–4] most critical ones. > Which services are most critical to document in depth?"

Lightweight scan (ALL services): tech stack, exposed endpoints/topics/events, data models owned, env vars, Dockerfile/deployment config. Deep scan (user-selected): internal code structure, handler logic, error handling, full file mapping, test coverage.

If monolith or single app with many modules: > "This is a large project with [N] components. I found: [list them]. > Which ones should I focus on? I recommend starting with [top 3–4 by importance], > and I can document the rest in a follow-up pass."

Wait for user to confirm scope before continuing.

Infrastructure-as-Architecture (Microservices only)

Before scanning individual services, read the infrastructure layer — it IS the architecture map:

# Docker compose — shows service dependencies, ports, networks
cat docker-compose*.yml 2>/dev/null

# Kubernetes — shows deployments, services, ingress
find . -path "*/k8s/*" -o -path "*/helm/*" -o -path "*/kubernetes/*" | head -30

# API gateway config
find . -name "nginx.conf" -o -name "kong.yml" -o -name "traefik.*" -o -name "envoy.*" | head -10

# Message broker config
find . -name "*.proto" -o -name "asyncapi.*" -o -name "*.avsc" | head -20

From this, build an initial service topology before looking at any service code:

• Which services exist and their ports
• Which services depend on which (links, depends_on, network policies)
• What shared infrastructure exists (databases, message brokers, caches, object storage)
• What the external entry points are (API gateway, load balancer, CDN)

Present this topology to the user for confirmation before deep-scanning individual services.

Step 2b: Per-Component Analysis

For each component in scope, analyze:

Tech stack — Read dependency/config files:

• package.json, tsconfig.json (Node/TS)
• go.mod, go.sum (Go)
• requirements.txt, pyproject.toml, setup.py (Python)
• Cargo.toml (Rust)
• pubspec.yaml (Flutter/Dart)

If none of the above exist, check for other indicators (Gemfile, pom.xml, build.gradle, mix.exs, etc.) and adapt accordingly. Don't assume a fixed set of languages.

Entry points — Find main files:

• Look for main.*, index.*, app.*, server.* in src/ or root
• Check package.json main/bin fields, or [tool.poetry.scripts], etc.

Routes/Screens — Discover user-facing paths:

• Web: Grep for route definitions in the framework's style (React Router, Next.js pages/app dir, Express app.get, etc.)
• Mobile: Look for screen/navigation definitions

API endpoints — Find all route/handler definitions:

• REST: Grep for HTTP method decorators/calls (@Get, @Post, app.get(, router., etc.)
• GraphQL: Look for schema files, resolver definitions
• tRPC: Look for router definitions
• If no patterns match, read the main entry point and trace outward

Data models — Find schemas and types:

• Database migrations: migrations/, db/migrate/, alembic/
• ORM models: Look for model/entity definition patterns in the detected framework
• TypeScript types/interfaces: key type definition files
• Prisma schema, GraphQL type definitions, protobuf files

Environment variables — Find config:

• .env.example, .env.sample, .env.template
• Docker compose files for service-level env vars
• Config files that reference process.env, os.environ, os.Getenv, etc.

Build/run/test commands — Find all dev commands:

• package.json scripts section
• Makefile, Taskfile.yml, Justfile
• Docker and docker-compose files
• CI/CD configs (.github/workflows/, .gitlab-ci.yml, etc.)

Additional Fields for Microservices

If the project was classified as microservices, also capture for EACH service:

Service identity:

• Service name (as defined in docker-compose, k8s manifests, or code)
• Port(s) it listens on
• Whether it's user-facing (external) or internal-only

Data ownership:

• Which database(s) does this service own?
• Does it have its own DB, or share with another service?
• What are the primary tables/collections it manages?

Events & messages (produced and consumed):

• Message queue topics/channels this service publishes to
• Topics/channels it subscribes to / consumes from
• Look for: RabbitMQ channel/queue definitions, Kafka topic configs, Redis pub/sub, AWS SQS/SNS, NATS subjects, event emitter patterns
• Grep for: publish(, emit(, produce(, subscribe(, consume(, on(, queue/topic name strings in config files

Synchronous service-to-service calls:

• gRPC client stubs and proto imports
• HTTP calls to other internal services (look for internal base URLs, service discovery patterns, or hardcoded localhost: in dev

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ekuttan
• Source: ekuttan/codewiki
• License: MIT

Install and usage instructions live in the source repository linked above.