Make Repository Agentic Coding Ready (Deep Analysis Edition)

Transform this repository into a state-of-the-art Claude Code workspace. This skill ANALYZES the actual codebase first, then generates everything tailored to what it finds.

Phase 1: Pre-Flight Check

Verify git repo: git rev-parse --is-inside-work-tree
Check what exists:
- ls -la .claude/ 2>/dev/null - existing config
- wc -l CLAUDE.md 2>/dev/null - existing CLAUDE.md size
- ls .claude/skills/ .claude/agents/ .claude/rules/ 2>/dev/null
Report findings to user before proceeding

Phase 2: Deep Repository Analysis

Spawn 4 parallel subagents using the Task tool (subagent_type: Explore, thoroughness: very thorough). Each analyzes a different dimension.

Subagent 1: Architecture and Tech Stack

Prompt: "Analyze this repository's architecture and tech stack. Read config files (package.json, pyproject.toml, Cargo.toml, go.mod, Makefile, Dockerfile, docker-compose.yml, requirements.txt, setup.py, pom.xml, build.gradle). Map directory structure (top 3 levels). Identify: language, framework, package manager, build tool, runtime. Find entry points. Map key architectural components. Identify database, cache, queue, external service integrations. Check for monorepo structure. Return: tech stack summary, architecture overview, key components list, all build/run/test/lint commands you can find."

Subagent 2: Code Conventions and Patterns

Prompt: "Analyze coding conventions in this repository. Sample 10-15 source files across different directories. Detect: naming conventions (camelCase/snake_case/PascalCase), import style (absolute/relative, grouping), error handling patterns, type annotation usage (strict/minimal/none), docstring/comment style, testing patterns (framework, fixtures, mocks, file naming). Check for linter/formatter configs (.eslintrc, ruff.toml, .prettierrc, rustfmt.toml, mypy.ini, tsconfig.json). Return: conventions summary, detected patterns, exact tool commands for lint/format/typecheck/test."

Subagent 3: Workflow and CI/CD

Prompt: "Analyze the development workflow of this repository. Check git history: git log --oneline -30 for commit style. Check branches: git branch -r for naming patterns. Read CI/CD configs (.github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml). Check for pre-commit hooks (.pre-commit-config.yaml, .husky/). Check deployment configs (Dockerfile, fly.toml, render.yaml). Look for environment files (.env.example). Return: git workflow summary (branch naming, commit style), CI/CD pipeline description, deployment process, environment setup notes."

Subagent 4: Security and Dependencies

Prompt: "Analyze security patterns in this repository. Check secrets management (env vars, vault configs). Scan for hardcoded credential patterns. Check authentication implementation (JWT, OAuth, sessions, API keys). Check authorization patterns (RBAC, middleware, decorators). Review input validation approach. Check dependency freshness. Review CORS/CSP/security headers. Return: security patterns summary, any concerns found, auth architecture description."

Phase 3: Synthesis and User Questions

After all subagents return:

Synthesize findings into a coherent picture
Present the analysis summary to user
Ask targeted questions using AskUserQuestion based on what was found:
- Which skills to create (suggest based on detected stack)
- Whether to create custom agents (suggest based on project complexity)
- Architectural decisions or patterns that could not be inferred
- Known issues, gotchas, or workarounds to document
- External services or integrations to know about
External skills: Load ~/.claude/skill-registry.yaml (if it exists). Present available external skills grouped by category using AskUserQuestion (multi-select). Suggest skills that complement the detected workflow:
- For projects with complex features: suggest brainstorming, writing-plans, executing-plans
- For projects with tests: suggest test-driven-development
- For projects with CI/PR workflows: suggest requesting-code-review, finishing-a-development-branch
- For debugging-heavy projects: suggest systematic-debugging
- For multi-agent setups: suggest dispatching-parallel-agents
- Always explain: "These are community skills from external repos. You can also install them later with /install-skill."

Phase 4: Generate Artifacts

Generate everything based on analysis results, NOT generic templates.

4.1: CLAUDE.md (MUST be under 150 lines)

Only include what Claude MUST know every session:

Project name + 1-2 sentence description (from analysis)
Build/run/test/lint commands (ACTUAL commands found)
Code style rules that DIFFER from language defaults (from conventions analysis)
Workflow rules (from git/CI analysis)
Brief architecture overview
Critical warnings (from security analysis)
Use @.claude/rules/filename.md imports for detailed content

If an existing CLAUDE.md has useful content, preserve it but restructure to be lean.

4.2: .claude/settings.json

Generate hooks using ACTUAL detected tools:

PostToolUse (Edit|Write): Auto-format with the ACTUAL formatter (ruff, prettier, gofmt, etc.)
PreToolUse (Edit|Write): Secret detection adapted to project secret types
Permissions deny: Block reading .env, credentials, secret files

IMPORTANT: Use $TOOL_INPUT_FILE_PATH (not echo "$TOOL_INPUT" | grep) for file-based checks to avoid shell escaping issues. For secret detection in content, use a script file or simpler patterns.

4.3: Skills

Generate ONLY skills that make sense for this project:

Always create:

verify/SKILL.md - Using ACTUAL lint/typecheck/test commands
commit/SKILL.md - Using ACTUAL commit conventions from git history
ping-user/SKILL.md - Audio notification (macOS)

Create if relevant:

pr/SKILL.md - If project uses GitHub PRs
security-check/SKILL.md - Tailored to project auth patterns
code-simplifier/SKILL.md - Tailored to project conventions

Each skill MUST use the actual commands and patterns from the analysis. No placeholders.

4.4: Agents

Always create:

code-reviewer.md - Tailored to project tech stack, patterns, conventions. Include project-specific review points.

Create if relevant:

test-writer.md - Using project's actual test framework, fixture patterns, mock conventions

4.5: Rules (.claude/rules/)

Generate modular rules based on analysis:

patterns.md - Key coding patterns (with path scoping for monorepos)
known-issues.md - Known issues and workarounds
architecture.md - Detailed architecture (if complex project)
Path-scoped rules for distinct areas (api/, workers/, frontend/)

4.6: External Skills (from Registry)

For each external skill the user selected in Phase 3:

Fetch the SKILL.md from the source repo:

curl -sL "https://raw.githubusercontent.com/{repo}/{branch}/{path}/{skill-name}/SKILL.md"

Verify the response contains valid frontmatter (--- block with name field)
Check for dependency skills (from registry). If a dependency is not already installed, fetch it too. Confirm with user first.
Check for additional files in the skill directory:
```
gh api repos/{repo}/contents/{path}/{skill-name} --jq '.[].name' 2>/dev/null
```
Fetch any additional .md files found alongside SKILL.md.
Install to .claude/skills/{skill-name}/SKILL.md (project-level)
If the skill conflicts with an existing project skill of the same name, ask: "Overwrite / Skip / View diff?"

Note: External skills are installed as-is from their source. They are not modified or adapted — the originals are well-written and tool-agnostic.

4.7: Codex CLI Compatibility (Cross-Tool Support)

If the user uses OpenAI Codex CLI alongside Claude Code, add cross-tool compatibility:

AGENTS.md: Generate an AGENTS.md with the tool-agnostic subset of CLAUDE.md (commands, code style, workflow, architecture). Strip Claude-specific references (/deep-plan, /review-changes, subagent mentions). Same factual content, no Claude-specific workflow noise.
Do NOT symlink AGENTS.md to CLAUDE.md - CLAUDE.md contains Claude-specific workflow instructions that would confuse Codex. Keep as separate files with shared factual content.
Share project skills via symlink: Create .agents/skills as a symlink to .claude/skills so Codex discovers all project-level skills. Project skills (verify, commit, pr, ping-user, security-check, code-simplifier) use generic instructions that both tools can follow. Codex ignores Claude-specific frontmatter fields.
```
ln -s .claude/skills .agents/skills
```
Do NOT share global advanced skills (deep-plan, review-changes, update-memory, agentic-ready) - these reference Claude-specific tools (Task, subagents, AskUserQuestion) that Codex does not have. They live only in ~/.claude/skills/.
Check if command -v codex exists. If so, ask user if they want .codex/config.toml for project-specific Codex settings.
Add to .gitignore: .codex/ (Codex project config is personal)

4.8: Housekeeping

Add to .gitignore if not present:

.claude/settings.local.json
CLAUDE.local.md
.codex/

Add "Development with Claude Code" section to README.md listing available skills.

Phase 5: Verification

Verify CLAUDE.md is under 150 lines
Verify .claude/settings.json is valid JSON: python3 -c "import json; json.load(open('.claude/settings.json'))"
Verify no secrets were included in any generated file
Present summary to user for review before committing

Key Principles

Analysis-driven, not template-driven - every artifact reflects actual findings
CLAUDE.md is a constitution - only what Claude MUST know every session, under 150 lines
Skills are on-demand expertise - loaded when relevant
Hooks are deterministic rules - no LLM discretion
Agents are isolated specialists - focused context per task
Rules are conditional guidance - path-specific, detailed docs
Less is more - do not create artifacts that add no value for this specific project

agentic-ready