Workspace Setup — Split /init into docs/

1. When to Use

Do NOT use when the instruction file is already <200 lines or docs/arquitectura/ is already populated.

2. Agent Parameter

Optional --agent parameter determines the instruction file name.

Syntax: "setup for claude", "setup --agent gemini", or mention the CLI at the start.

--agent value	Instruction file created
claude	CLAUDE.md
gemini	GEMINI.md
codex / warp / crush / opencode / (default)	AGENTS.md

The content is identical regardless of filename. Only the name changes.

3. Steps

Step 1: Find base file

Look for CLAUDE.md, AGENTS.md, or GEMINI.md at the project root with substantial content.

Heuristic: the file contains sections like Architecture, Folder Structure, Key Services, API patterns, Environment config, Dependencies, Build commands.

If no substantial file is found → inform the user and abort.

Step 2: Create target directories

Create docs/arquitectura/. Also create docs/especificaciones/ and docs/manuales/ only if there is content for them.

Step 3: Split content

Use the mapping table to distribute sections from the base file into numbered docs.

See references/mapping-table.md for the detailed mapping with examples.

Quick reference:

Section from /init	Destination
Build commands, Dependencies/stack	Instruction file (stays)
Architecture (overview, structure, services, components, patterns)	→ docs/arquitectura/001-arquitectura.md
API patterns	→ docs/especificaciones/001-api-patterns.md
Environment config	→ docs/manuales/002-configuracion.md

Group related content into the same file. Use separate files only when topics are clearly distinct.

Section Detection Heuristics

Match H2 headers (## ) against these patterns:

Header matches	Destination
/architect|structure|overview|design|folder/i	→ docs/arquitectura/
/api|endpoint|route|pattern|response/i	→ docs/especificaciones/
/env|config|setup|variable|connection/i	→ docs/manuales/
/build|dev|test|lint|command|script/i	stays in instruction file
/depend|stack|tech|framework|version/i	stays in instruction file

If a section doesn't match, keep it in instruction file and flag for user review.

Step 3b: Extract conditional rules (--agent claude only)

If --agent is claude, extract technology-specific patterns into .claude/rules/:

1. Detect the project's stack from the base file content (TypeScript, Java, SQL, etc.)
2. Create up to 2-3 files in .claude/rules/<tech>.md with frontmatter globs
3. Each file should be <30 lines with conventions specific to that technology

See references/rules-templates.md for templates by technology.

Example:

.claude/rules/angular.md     → globs: ["src/**/*.ts", "src/**/*.html"]
.claude/rules/sql.md         → globs: ["**/*.sql"]

If --agent is NOT claude, skip this step entirely.

Step 4: Minimize instruction file

Create or overwrite the instruction file (name determined by --agent parameter).

Keep only:

• Name and description (1-2 lines)
• Stack (language, framework, main dependencies)
• Commands (dev, build, test)
• Reference to docs/arquitectura/
• Base workspace rules

See references/instruction-file-minimal.md for the template.

Special case for --agent gemini: use @docs/arquitectura/001-arquitectura.md syntax (Gemini CLI native imports) instead of > See docs/arquitectura/....

Target: <200 lines in the final instruction file.

Step 5: Verify

1. Count lines of the resulting instruction file — MUST be <200
2. Confirm every H2 section from the original file exists in exactly one destination
3. If docs/arquitectura/ has more than 6 files, consolidate — over-splitting defeats discoverability
4. Report to the user: files created, line count of instruction file, any sections that were ambiguous

4. NEVER Do This

• NEVER delete the original file before confirming all content is placed — data loss is unrecoverable
• NEVER create more than 6 architecture files from a single /init — over-splitting defeats discoverability
• NEVER put build/dev commands in docs/ — they are high-frequency lookups that belong in the instruction file
• NEVER create .claude/rules/ for --agent values other than claude — other CLIs don't support conditional rules
• NEVER create docs/planes/, docs/decisiones/, or tools/ — those fill on demand via workspace-guide
• NEVER create symlinks between instruction files — generates exactly one file per agent type

5. Edge Cases

• Multiple instruction files (CLAUDE.md + AGENTS.md both with content): ask user which is source, operate on that one only
• docs/ already exists with files: do NOT overwrite — use next available number, warn user
• /init output < 50 lines: do NOT split — inform user file is already minimal
• No recognizable H2 sections: abort — manual splitting needed
• Stack not in rules-templates.md: skip .claude/rules/ creation for that stack, inform user

6. After Setup

Once the split is complete:

1. workspace-guide takes over for ongoing conventions (directory structure, file numbering, tool creation)
2. The user can start creating documents in docs/planes/, docs/decisiones/ as needed
3. When tools are created later, run npx workspace-update sync to register them

Install workspace-guide: npx skills add tacuchi/workspace-tools@workspace-guide