Claude Code Monorepo Scaffolding

Your goal is to create an initial setup for Claude Code in a large pre-existing monorepo project, including agent instructions and context information. You work in close collaboration with the user to obtain the required base knowledge about the goals and structure of the project as well as each sub-project.

Additional user arguments: $ARGUMENTS

Language hint: Always create all generated document content in English, while continuing to speak to the user in the language of their choice.

Platform hint: Instructions and templates assume a Linux host with GNU coreutils. Adapt to the detected user OS.

• macOS — Substitute BSD equivalents for GNU-only utilities.
• Windows — Still use .sh files (skip irrelevant chmod +x), assuming Git Bash is available at runtime. Highlight this requirement in the Debriefing. Set "shell": "bash" on command hooks in settings.json. Omit the entire sandbox block from settings.json as long as bash sandboxing is unsupported.

Agent Content Principles

When generating content for .md files below, you are writing prompts and context for other AI coding agents. Follow these principles to optimally tailor your instructions to their needs:

• Concise — Minimize token usage. Prefer keywords and terse bullet points over prose.
• Structured — Use compact Markdown to delineate connected aspects.
• Actionable — Generate concrete operational directives, not abstract guidelines. Avoid aspirational quality statements, general engineering practices, blanket prohibitions.
• Referential — Provide pointers to key code files the agents can read themselves. Do not describe how code works in agent instructions as such duplication leads to drift.
• Scoped — Context is hierarchical. The central CLAUDE.md applies to every scope and must only contain core project identity and semantics. Sub-project CLAUDE.md, rules and agent instructions progressively disclose domain- and task-specific knowledge.
• Durable — Only include details that remain invariant under normal codebase evolution. Avoid specific technology versions. Reference namespaces or search terms instead of single artifacts.

Workflow

1. Begin execution by creating a formal task list for progress tracking using the TaskCreate tool. Create a task for each of the following phases (##) and sub-phases (###). Do not duplicate the contents in the description, only reference this skill (abc-init:monorepo) and the workflow item.
2. Create a dependency chain between all tasks using TaskUpdate, setting addBlockedBy to the predecessor task.
3. Work through the TaskList using TaskUpdate to mark tasks as in_progress and completed as you go.

Phase 1: Reconnaissance

1. Use Explore agents to scan the repository and build an initial understanding of its structure
   • Top-level directory content that hints at used technologies (e.g. package.json, composer.json, Cargo.toml, go.mod, Makefile, Dockerfile)
   • Existing documentation (e.g. README.md, CONTRIBUTING.md or docs/)
   • Style (e.g. imperative mood) and common patterns (e.g. ticket numbers) in commit messages from the git log.
2. Read any discovered documentation and technology manifest files
3. Check for an existing CLAUDE.md or .claude/ directory — if found, establish if the user wants to amend or replace these.
4. Summarize your findings and conclusions briefly for the user and ask if they want to comment or add information.

Phase 2: User Interview

Interview the user to establish the project's base details and sub-project boundaries. Use AskUserQuestion where appropriate to keep the conversation structured.

Offer pre-defined choice options if likely answers to a question are already known from context. However, never skip parts of the interview even if all answers could be inferred. The purpose of the interview is to include tribal project knowledge not captured by reconnaissance.

General Question Catalogue

1. What is the name of the project?
2. Who is the project creator and/or maintainer (company/organization)?
3. What is the overall purpose of the project (one-sentence summary)?
4. What is the production scale of the project (data size, number of users)?
5. What is the general technological approach of the project (one-sentence summary)?
6. What are key concepts or vocabulary that every developer needs to learn on their first day (independent of sub-project)?
7. What sub-projects or applications exist in this monorepo?

Sub-Project Question Catalogue

Go through every sub-project established in general question 6 and repeat these questions for each of them.

1. What is the name of the sub-project or the development team (e.g. "backend" / "frontend")? (If the name is more than one word, also establish a short slug to use in generated files.)
2. What are the main purposes / functions of the sub-project?
3. What are key terms or vocabulary that every developer in this sub-project needs to know?
4. What are the main technologies used (programming language, framework, deployment...)?
5. Does this sub-project live under a dedicated root directory?
   • If yes: what is the path to that directory relative to the project root?
   • If no: what file/path glob pattern uniquely identifies its source files? (e.g. src/Payments/**/*.ts) This is typically <namespace-path>/**/*.<language-extension>.
6. What are the key source directories?
7. How are automated tests organized and run?
8. Are there tools for linting or other automated code quality control?

Phase 3: Generate Artifacts

3a — Claude Code Settings

1. Copy the settings template to <project-dir>/.claude/settings.json
2. Copy the statusline template to <project-dir>/.claude/statusline.sh and make it executable (chmod +x).
3. Duplicate the permissions with the {{SUB-PROJECT-PATH}} placeholder for each sub-project.
4. Inject {{GITIGNORE-EXCLUSIONS}} into the sandbox config, limiting write access to version-controlled files only.
5. Replace general {{PLACEHOLDERS}} with answers from the general user interview questions.

3b — Central CLAUDE.md

1. Copy the template to <project-dir>/CLAUDE.md
2. Replace the {{PLACEHOLDERS}} with answers from the general user interview questions.

The content is written for AI, not humans. There is no need for verbose introductions or explanations. Keep this file as brief as possible to preserve tokens. Prefer keywords and enumeration over continuous text. Use clear section headers and other Markdown formatting to demark connected aspects.

3c — Local Override Files

1. Copy the template to <project-dir>/CLAUDE.local.md.example
2. If a .gitignore file exists in the project root, add the following entries (if not already present):

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

3d — Sub-Project Explorer Agents

Perform these steps for every established sub-project:

1. Copy the template to <project-dir>/.claude/agents/<sub-project-slug>-explorer.md
2. Replace the {{PLACEHOLDERS}} with acquired context for the respective sub-project. Add available {{MCP-SEARCH-TOOLS}} for read-only exploration. Omit the native Glob and Grep tools if suitable MCP replacements are present.
3. Use a general purpose Explore agent to perform a more thorough exploration of the sub-project's code and add additional context information and instructions that are helpful to navigate the code structure as well as common conventions and nomenclature.

After creation of all explorer agents, modify `.claude/setti