Help us improve
Share bugs, ideas, or general feedback.
From bishx
Scans codebase to update CLAUDE.md and AGENTS.md with production-quality docs on stack, structure, models, APIs, services, repositories, auth, and frontend.
npx claudepluginhub bish-x/claude-bishxHow this skill is triggered — by the user, by Claude, or both
Slash command
/bishx:init-syncThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You scan the current project and fill `CLAUDE.md` and `AGENTS.md` with real data from the codebase. This works both on fresh templates (with `<!-- bishx:init:xxx -->` markers) and on previously filled files (updates existing content).
Analyzes unfamiliar codebases to generate structured onboarding guides with architecture maps, key entry points, conventions, and starter CLAUDE.md.
Analyzes unfamiliar codebases to generate structured onboarding guides with architecture maps, key entry points, conventions, and starter CLAUDE.md. Use for new projects or initial Claude Code setup.
Scaffolds AGENTS.md, ARCHITECTURE.md, and docs/ structure to make codebases legible to AI agents. Analyzes structure with bash recon, generates progressive disclosure docs, audits existing artifacts for coherence.
Share bugs, ideas, or general feedback.
You scan the current project and fill CLAUDE.md and AGENTS.md with real data from the codebase. This works both on fresh templates (with <!-- bishx:init:xxx --> markers) and on previously filled files (updates existing content).
The output quality must match production-grade project documentation — deep, specific, with exact file paths, counts, and lists.
Core principle: Document what ACTUALLY exists. Don't force the project into a predefined template. If the project has Controllers — write Controllers, not Routes. If it has Repositories — write Repositories, not DAOs. Adapt section names, structure, and depth to the real architecture. The examples below are for quality reference, not for copying verbatim.
CLAUDE.md must exist in project root. If not — tell user to run /bishx:init first.AGENTS.md must exist in project root. If not — tell user to run /bishx:init first.Search for project manifests to identify the stack:
package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml,
composer.json, Gemfile, pom.xml, build.gradle, mix.exs, pubspec.yaml,
tsconfig.json, vite.config.*, next.config.*, nuxt.config.*,
docker-compose.yml, Dockerfile, Makefile
Read each found manifest. Extract: language, framework, ALL dependencies with versions.
This is NOT a surface scan. You must understand the codebase deeply.
Run ls (depth 2-3) on the project root. Map every significant directory.
Find all model definitions:
class.*Base, SQLAlchemy models, Pydantic models, dataclassesFor each: note file path, count, list key model names.
Find all route/endpoint definitions:
@router.get/post/put/delete, APIRouterrouter.get/post, app.get/postmux.HandleFunc, gin.GET/POSTapp/ or pages/ directory structureFor each: note file paths, count, list key endpoints, identify namespaces (admin, public, internal).
Find service layer files. Note: location, count, key services.
Find data access layer. Note: base class (if any), file paths, count, examples.
Find auth mechanisms: middleware, decorators, guards, permission checkers. Note: auth method (JWT/JWE/sessions/OAuth), permission model, key files.
Find standardized response wrappers (envelope, DTO, serializers).
Find all middleware. List each with one-line description.
Find background tasks, cron jobs, queue consumers. Note mechanism and examples.
Find config management approach (env, runtime config, feature flags).
Find existing docs (docs/, README.md, API specs, architecture docs).
Identify domain-specific terms from model names, comments, README.
Read CLAUDE.md. Replace placeholder sections AND add new sections if they don't exist.
Replace <!-- bishx:init:project_description --> with 1-2 sentence description.
Source: README.md, package.json description, pyproject.toml metadata.
Replace <!-- bishx:init:stack --> with compact bullet list:
- Backend: Python 3.13, FastAPI, SQLAlchemy async, Alembic, Pydantic v2
- Frontend: React 19, TypeScript, Vite, Tabler (HTML→React conversion)
- DB: PostgreSQL, Redis
- Auth: LDAP/AD → JWE tokens
Only include categories that actually exist. Be specific with versions.
Insert AFTER Stack, BEFORE Security. Content:
Example:
## Environment
- venv: `.venv` in project root, activate via `python3.13`
- Full codebase context: `docs/CODEBASE_CONTEXT.md`
- Architecture details: `docs/plans/v1/implementation-plan.md`
Insert AFTER Environment, BEFORE Security. Brief (2-3 sentences):
Example:
## Backend Architecture (`backend/`)
Base backend architecture in `backend/app/`. New modules follow these patterns. Architecture can evolve if justified — but don't break the foundation (DAO, DTO, ResponseEnvelope, async everywhere, session injection)
If current content is only generic OWASP rules, enhance with project-specific security concerns detected from the codebase (encryption, compliance requirements, network restrictions, etc.).
Insert AFTER Security. Brief notes:
Example:
## Frontend
- Tabler HTML → HTML→React conversion, no Tailwind
- Avoid generic AI aesthetics. Follow the framework's style.
This is the DEEP documentation file. It must be thorough enough that a new agent can understand the entire codebase without reading source files.
Replace {PROJECT_NAME} with actual project name.
Replace <!-- bishx:init:project_description --> with 2-3 sentence description.
Replace <!-- bishx:init:stack_detailed -->.
Create subsections per layer with **bold labels** and exact versions:
### Backend
- **Runtime:** Python 3.13
- **Framework:** FastAPI
- **ORM:** SQLAlchemy 2.x async
- **Migrations:** Alembic
- **Validation:** Pydantic v2
- **Cache/Messaging:** Redis 7+
- **DB:** PostgreSQL 16+
### Frontend
- **Runtime:** React 19
- **Language:** TypeScript 5
- **Bundler:** Vite 6
- **UI Framework:** Tabler (HTML→React conversion, no Tailwind)
- **Router:** React Router v7
- **State:** Zustand
- **Data Fetching:** TanStack React Query v5
- **HTTP Client:** Axios
### Auth
- **Source:** LDAP/AD bind
- **Tokens:** JWE (access 15min / refresh 30d HttpOnly)
Include ALL layers: Backend, Frontend, ML/AI, Auth, Monitoring, Infrastructure — whatever exists.
Replace <!-- bishx:init:project_structure --> with FULL architectural breakdown.
This is NOT just a directory tree. Create subsections for EACH architectural layer found:
Discover the actual layers the project uses. Common ones: Models, DAO/Repository, Schemas/DTOs, Routes/Controllers, Services, Auth, Response Format, Config, Middleware, Workers, Scheduler — but only document what's actually there. Skip what doesn't exist. Add layers not listed here if the project has them.
For each layer found, include: Location, Count (if countable), key names/examples.
Example for one subsection:
### Models
- **Location:** `backend/app/main_dao/models.py`
- **Count:** ~20 models in one file
- **Key models:** User, Role, UserRole, Conference, Transcript, AudioFile, Tag, Notification, AuditLog
### DAO Layer
- **BaseDAO[T]:** `backend/app/main_dao/base.py` — Generic CRUD with cursor pagination
- **DAO files:** `backend/app/dao/` — 24 files, inherit BaseDAO
- **Examples:** UserDAO, ConferenceDAO, TranscriptDAO, TagDAO, NotificationDAO
Discover the actual frontend structure. Common layers: Features/Pages, UI Components, Layout, State Management, Hooks/Composables, Routes — but adapt to what's actually there (Vue has composables, not hooks; Angular has modules; etc.).
For each layer found, include: Location, Count, lists.
Routes — prefer table format:
| Path | Component | Feature |
|------|-----------|---------|
| `/` | HomePage | home |
| `/login` | LoginPage | auth |
Replace with table of ALL found documentation files:
| Document | Description |
|----------|-------------|
| [README.md](README.md) | Navigation hub |
| [docs/architecture.md](docs/architecture.md) | Services architecture |
Extract domain-specific terms from models, README, comments:
| Term | Meaning |
|------|---------|
| Conference | TrueConf video call (2-60 min) |
If no clear domain terms found — omit this section entirely.
Replace <!-- bishx:init:patterns -->.
Per-layer list of ACTUAL patterns found in code (not recommendations):
### Backend
- DAO pattern (not Repository, not Active Record)
- Async everywhere (asyncpg, aiohttp, aioredis)
- Pydantic v2 schemas for validation
- Cursor-based pagination (not offset)
- Soft delete (deleted_at, deleted_by)
- ResponseEnvelope for all API responses
### Frontend
- Feature-based structure (not by file type)
- Zustand for state management
- React Query for server state
Be specific — mention what pattern IS used and what it's NOT (like the voicer example).
[bishx:init-sync] Done
- CLAUDE.md: N sections filled, M sections added
- AGENTS.md: N sections filled, M sections added
- Stack: {one-line stack summary}
- Architecture: {count} layers documented
- Patterns: {count} patterns identified
app/models.py". Don't write "some routes" — write "20+ files in api/v1/routes/".