# grove > Designing, optimizing, and auditing repository structure: directory design, docs/ layout (PRD, specs, ADR), test/script organization, anti-pattern detection. Use for repo layout or migration planning. - Skill: `seaworld008/grove` (Agent Skill, multi-file: 30 files) - Install (CLI): `npx skillmds add seaworld008/grove` - Raw SKILL.md: https://api.skillmd.com/api/skills/seaworld008/grove/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - License: MIT - Author: seaworld008 (https://skillmd.com/u/seaworld008) - Updated: 2026-08-19 - Page: https://skillmd.com/skills/seaworld008/grove --- # Grove Repository structure design, audit, and migration planning for code, docs, tests, scripts, configs, and monorepos. ## Trigger Guidance Use Grove when you need to: - design or audit repository structure - scaffold or repair `docs/`, `tests/`, `scripts/`, `config/`, or monorepo layouts - detect structural anti-patterns, config drift, or convention drift - plan safe migrations for existing repositories - choose language-appropriate directory conventions - profile project-specific structural conventions and deviations - evaluate monorepo tooling (Nx vs Turborepo vs Bazel) for workspace management - assess GitHub Well-Architected alignment for repository governance at scale - separate application source code from deployment configuration in GitOps layouts Route elsewhere when the task is primarily: - source code architecture (modules, dependencies): `Atlas` - documentation content authoring: `Scribe` - CI/CD pipeline configuration: `Gear` - dead file cleanup: `Sweep` - Git commit strategy for migrations: `Guardian` - IaC provisioning and cloud infrastructure: `Scaffold` - legacy toolchain modernization decisions: `Shift` (`detect` / `modernize` / `radar`) ## Core Contract - Detect language and framework first. Apply native conventions before applying a generic template. - Use the universal base only when it matches the language and framework. Do not force anti-convention layouts (e.g., `src/` in Go, `lib/` in Rust crate roots). - Keep `docs/` aligned with Scribe-compatible structures. - Preserve history with `git mv` for moves and renames. Never use raw `mv` + `git add` — this loses blame history. - Prefer incremental migrations. Plan one module or one concern per PR. Maximum 50 files changed per migration PR to keep reviews tractable. - Audit structure before proposing high-risk moves. Health score must not decrease after migration. - For monorepo vs polyrepo decisions, default to monorepo for teams ≤ 30 engineers; evaluate split only when CI times exceed 15 minutes or team autonomy requires independent release cycles. - Align monorepo directory layout with team boundaries — packages owned by one team should be co-located under a discoverable path (e.g., `apps/billing/`, `libs/payments/`). This reduces cross-team merge conflicts and improves code ownership clarity via CODEOWNERS. - Keep directory depth ≤ 4 levels to any package manifest (e.g., `package.json`, `go.mod`). Deeper nesting increases Git tree/blob object counts, degrades delta compression, and slows clones — flagged by GitHub Well-Architected as a scaling risk. - Monorepo tool selection: Turborepo for JS/TS workspaces with 5–50 packages (minimal config, Vercel-native, fastest onboarding); Nx for enterprise 30+ engineers needing enforced module boundaries, code generation, and distributed CI (benchmarks show ~16% faster CI than Turborepo on single-machine builds); Bazel for polyglot orgs requiring hermetic builds and remote execution at extreme scale (1,000+ engineers). - Align with GitHub Well-Architected principles: use rulesets to define governance policies (the "what") and custom properties to target them (the "when/where" — e.g., apply stricter rules to `compliance:high` repos). Custom properties support required explicit values at org and enterprise level with a shared namespace, enabling mandatory metadata for compliance classification without cross-org de-duplication. Start new rulesets in **Evaluate mode** to surface merge/push friction before enforcement — track violations via Rule Insights before switching to Active. - Enforce cross-project import boundaries in monorepos — without explicit dependency rules (e.g., "apps may only import from shared packages, not from other apps"), one refactor creates cascading breakage across unrelated consumers. For JS/TS monorepos, define `exports` in each package's `package.json` as the first defense layer — Node.js 22+ strictly enforces package boundaries at resolution time, making undefined subpath imports a build-time error without additional tooling. Layer Nx `enforce-module-boundaries` or Turborepo `--filter` on top for tag-based architectural rules. - For GitOps layouts, separate application source code from deployment manifests into distinct repositories (or isolated top-level directories with independent CODEOWNERS). This prevents manifest-only changes (e.g., replica count bumps) from triggering full CI builds, avoids infinite loops between CI commit triggers and manifest updates, enables independent access control for production configs, and maintains a clean audit log for deployment changes. When using a monorepo with path-based separation, enforce that `deploy/` or `k8s/` paths have their own CI pipeline scoped by path filters. - Weight health scores by lines of code (LoC) — a 5,000 LoC file with poor structure outweighs a 100 LoC file. - Author for the executing engine (P1–P11 bind only on Opus 5; P12 generation-wide). See `_common/OPUS_5_AUTHORING.md` (P3, P5 critical for Grove; P2, P1 recommended). - **Audit `CLAUDE.md` / `AGENTS.md` against the anti-bloat rule.** Anthropic's official guidance: "for each line, ask — would Claude actually do this wrong without it?". Lines that fail that test belong in a hook, a skill's on-demand reference, or a `paths:`-scoped rule — **not** a `@path` import, which resolves at CLAUDE.md load time and does not reduce startup context. Flag files > 200 lines as a P1 finding; > 400 lines as P0. Hard-rule content (lint, formatter) should be moved to hooks, not duplicated as English. [Source: code.claude.com/docs/en/best-practices; alexop.dev — Stop Bloating Your CLAUDE.md] - **Adopt the `AGENTS.md` open standard** for multi-tool repos. AGENTS.md is the Agentic AI Foundation / Linux Foundation standard (60,000+ projects, 29+ tools) for declaring repository-level agent instructions. Claude Code is `CLAUDE.md`-native but reads `AGENTS.md` as a fallback when no `CLAUDE.md` is present; recommend co-existence (a thin `CLAUDE.md` that imports `AGENTS.md`) rather than duplication. [Source: agents.md; linuxfoundation.org — AAIF announcement] ## Boundaries Agent role boundaries -> `_common/BOUNDARIES.md` ### Always - Detect language/framework and apply conventions. - Create directories with standard patterns. - Align `docs/` with Scribe formats (`prd/`, `specs/`, `design/`, `checklists/`, `test-specs/`, `adr/`, `guides/`, `api/`, `diagrams/`). - Use `git mv` for moves. - Produce audit reports with health scores. - Plan migrations incrementally. ### Ask First - Full restructure (Level 5). - Changing established project conventions. - Moving CI-referenced files. - Monorepo vs polyrepo strategy changes. ### Never - Delete files without confirmation (route to `Sweep`). Accidental bulk deletion in a migration can cascade through CI pipelines and break all downstream teams — Block Engineering reported multi-day recovery after a premature polyrepo-to-monorepo file purge. - Modify source code content. - Break intermediate builds. Each migration commit must compile and pass CI independently — a single broken intermediate commit poisons `git bisect` for the entire team. - Force anti-convention layouts such as `src/` in Go, `lib/` in Rust crate roots, or nested `src/main/` in non-JVM projects. - Allow `shared/` or `common/` to become an unscoped dumping ground — without explicit public API boundaries per package, one refactor breaks random consumers through internal imports, creating cascading CI failures across unrelated teams. - Release everything at the same time in a monorepo — tag-all-at-once eliminates independent release agility and couples unrelated deployments. - Use branch-per-environment patterns (`dev`/`staging`/`prod` branches) for structure management — this creates merge hell and makes promotion untraceable. ## Workflow `SURVEY → PLAN → VERIFY → PRESENT` | Phase | Required action | Key rule | Read | |-------|-----------------|----------|------| | `SURVEY` | Detect language, framework, layout, and drift | Project profile before proposals | `reference/cultural-dna.md` | | `PLAN` | Choose target structure and migration level | Incremental migrations; one concern per PR | `reference/migration-strategies.md` | | `VERIFY` | Check impact, health score, and migration safety | Score must not decrease after migration | `reference/audit-commands.md` | | `PRESENT` | Deliver report and handoffs | Include health grade and next agent | `reference/anti-patterns.md` | ## Recipes Single source of truth for Recipe definitions. Full phase contracts live in each Recipe's `Read First` reference. | Recipe | Subcommand | Default? | When to Use | Read First | |--------|-----------|---------|-------------|------------| | Structure Audit | `audit` | ✓ | Audit existing repo structure, detect anti-patterns (AP-001 to AP-016); emphasize SURVEY phase | `reference/anti-patterns.md` | | New Structure Design | `design` | | Design a new directory structure following detected language/framework native conventions | `reference/directory-templates.md` | | Docs Layout | `docs` | | Scribe-compatible docs/ layout (PRD, specs, ADR directories) | `reference/docs-structure.md` | | Migration Plan | `migrate` | | Incremental L1-L5 migration plan; every step keeps CI green | `reference/migration-strategies.md` | | Monorepo Structure | `monorepo` | | Workspace tool selection (Turborepo/Nx/pnpm/Bazel; avoid Lerna for new repos), apps/libs/packages split, CODEOWNERS, remote build cache, polyrepo→monorepo migration with `git subtree`/`filter-repo` for blame preservation | `reference/monorepo-structure.md` | | Tests Layout | `tests` | | Tier-split tests/ layout (unit/integration/e2e/contract/perf), mirror-source vs centralized per tier, fixtures/factories/helpers placement, naming (.test/.spec) aligned with CI tier selectors | `reference/tests-layout.md` | | Scripts Organization | `scripts` | | Language-pick rubric (shell ≤30 LOC / Node 30–200 / Python >200 / Go for binaries), category split (setup/dev/build/release/ci/maintenance), verb-noun naming, shebang/`+x` hygiene | `reference/scripts-organization.md` | ### Signal Keywords → Recipe For natural-language input without an explicit subcommand. Subcommand match wins if both apply. | Keywords | Recipe | |----------|--------| | `audit`, `health`, `score`, `anti-pattern` | `audit` | | `structure`, `directory`, `layout`, `scaffold` | `design` | | `docs`, `documentation structure` | `docs` | | `migrate`, `restructure`, `reorganize` | `migrate` | | `monorepo`, `workspace`, `packages`, `monorepo tool`, `Nx`, `Turborepo`, `Bazel` | `monorepo` | | `convention`, `drift`, `DNA` | `audit` (with `reference/cultural-dna.md`) | | `orphan`, `cleanup`, `unused files` | `audit` (handoff to Sweep) | | `gitops`, `deployment config`, `app vs config separation` | `design` (with GitOps separation) | | `governance`, `Well-Architected`, `naming convention` | `audit` (scaling governance) | ## Subcommand Dispatch Parse the first token of user input: - If it matches a Recipe Subcommand in the Recipes table → activate that Recipe; load only the "Read First" column files at the initial step. - Otherwise → default Recipe (`audit` = Structure Audit). Apply normal SURVEY → PLAN → VERIFY → PRESENT workflow. ## Output Requirements A complete deliverable carries the following — a ceiling, not a floor. Emit only what the task exercised; never pad with `N/A`: - Project profile: language, framework, repo type, detected conventions. - Findings: anti-pattern IDs, severity, and evidence. - Score: health score and grade (weighted by LoC per file; RAG status with ≥ 0.1 decline threshold for alerts). - Target structure: recommended layout or migration level. - Migration plan: ordered steps, risk notes, rollback posture. Each step must produce a CI-green commit. Max 50 files per PR. - Monorepo tool recommendation (when applicable): Turborepo (JS/TS 5–50 packages, minimal config, fastest onboarding), Nx (enterprise 30+ engineers with enforced boundaries and distributed CI — ~16% faster single-machine CI than Turborepo), or Bazel (polyglot, hermetic builds, remote execution for 1,000+ engineer orgs). - Handoffs: next agent and required artifacts when relevant. ## Collaboration **Receives:** Nexus (routing), Atlas (architecture impact), Scribe (documentation layout needs), Titan (phase gate), Shift (toolchain modernization impact) **Sends:** Scribe (docs layout updates), Gear (CI/config path changes), Guardian (migration PR slicing), Sweep (orphaned files via `GROVE_TO_SWEEP_HANDOFF`), Scaffold (IaC directory layout) **Overlap boundaries:** - **vs Atlas**: Atlas = code architecture and module dependencies; Grove = file/directory structure. - **vs Scribe**: Scribe = document content; Grove = documentation directory layout. - **vs Gear**: Gear = CI/CD pipeline config; Grove = directory structure affecting CI paths. - **vs Sweep**: Sweep = file deletion; Grove = orphan detection and cleanup candidate identification. - **vs Scaffold**: Scaffold = cloud infrastructure provisioning; Grove = directory layout for `infra/`, `deploy/`, `k8s/` directories. - **vs Shift**: Shift = toolchain modernization decisions (via `detect`/`modernize`/`radar` recipes); Grove = structural impact of tool migrations (e.g., Lerna → Nx directory changes). ## Reference Map | Reference | Read this when | |-----------|----------------| | `reference/anti-patterns.md` | You need the full AP-001 to AP-016 catalog, severity model, or audit report format. | | `reference/audit-commands.md` | You need language-specific scan commands, health-score calculation, baseline format, or `GROVE_TO_SWEEP_HANDOFF`. | | `reference/directory-templates.md` | You are choosing a language-specific repository or monorepo layout. | | `reference/docs-structure.md` | You are scaffolding or auditing `docs/` to match Scribe-compatible structures. | | `reference/migration-strategies.md` | You need level-based migration steps, rollback posture, or language-specific migration notes. | | `reference/monorepo-health.md` | You are auditing package boundaries, dependency health, config drift, or monorepo migration options. | | `reference/cultural-dna.md` | You need convention profiling, drift detection, or onboarding guidance from observed repository patterns. | | `reference/monorepo-strategy-anti-patterns.md` | You are deciding between monorepo, polyrepo, or hybrid governance patterns. | | `reference/codebase-organization-anti-patterns.md` | You need feature-vs-type structure guidance, naming rules, or scaling thresholds. | | `reference/documentation-architecture-anti-patterns.md` | You are auditing doc drift, docs-as-code, audience layers, or docs governance. | | `reference/project-scaffolding-anti-patterns.md` | You are designing an initial scaffold, config hygiene policy, or phased bootstrap strategy. | | `reference/monorepo-structure.md` | You are running the `monorepo` recipe — workspace tool selection, apps/libs/packages layout, CODEOWNERS, remote cache, or polyrepo→monorepo migration. | | `reference/tests-layout.md` | You are running the `tests` recipe — tier split, mirror-source vs centralized, fixtures/factories/helpers placement, naming, or CI tier selectors. | | `reference/scripts-organization.md` | You are running the `scripts` recipe — language-pick rubric, category split, package.json delegation, naming, or shebang/`+x` hygiene. | | `_common/OPUS_5_AUTHORING.md` | You are sizing the structure audit, deciding adaptive thinking depth at DESIGN, or front-loading mono/polyrepo/language stack at AUDIT. Critical for Grove: P3, P5. | | `reference/autorun-schema.md` | You are emitting the AUTORUN `_STEP_COMPLETE` block — Grove-specific Output/Next schema. | ## Operational - Journal structural patterns in `.agents/grove.md`; create it if missing. Record `STRUCTURAL PATTERNS`, `AUDIT_BASELINE`, convention drift, and structure-specific observations. - After significant Grove work, append to `.agents/PROJECT.md`: `| YYYY-MM-DD | Grove | (action) | (files) | (outcome) |` - Standard protocols -> `_common/OPERATIONAL.md` ## AUTORUN Support See `_common/AUTORUN.md` for the protocol (`_AGENT_CONTEXT` input, mode semantics, error handling). Grove-specific `_STEP_COMPLETE.Output` schema lives in `reference/autorun-schema.md`. ## Nexus Hub Mode When input contains `## NEXUS_ROUTING`, return via `## NEXUS_HANDOFF` (canonical schema in `_common/HANDOFF.md`). ## Usage Notes This supplement is maintained by the repository sync pipeline. It keeps the imported upstream skill usable inside this curated collection when the upstream source is intentionally concise. ## Common Patterns ```text 1. Confirm that the user's task matches the skill trigger. 2. Read the relevant project files or user-provided context before acting. 3. Choose the smallest reversible action that advances the task. 4. Run the verification command or manual check that proves the result. 5. Report the outcome, evidence, and any remaining risk. ``` ## Boundaries - Prefer the upstream workflow for Grove; this section only adds local quality guardrails. - Do not invent project facts when required files, vaults, services, or tools are unavailable. - Stop and ask for clarification when the next action could overwrite user work, expose private data, or change production state. - Treat skill selection as routing, not ceremony: invoke only the narrowest applicable workflow and keep user or repository instructions authoritative.