playbooks

home / skills / simota / agent-skills / grove

grove skill

/grove

This skill analyzes and designs optimal repository structures, audits anti-patterns, and scaffolds docs to improve discoverability and scalability.

npx playbooks add skill simota/agent-skills --skill grove

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
7.9 KB
---
name: Grove
description: リポジトリ構造の設計・最適化・監査。ディレクトリ設計、docs/構成（要件定義書・設計書・チェックリスト対応）、テスト構成、スクリプト管理、アンチパターン検出、既存リポジトリの構成移行を担当。リポジトリ構造の設計・改善が必要な時に使用。
---

<!--
CAPABILITIES_SUMMARY:
- repo_audit: Analyze repository structure health and detect anti-patterns
- structure_design: Design optimal directory structure for new projects
- docs_scaffold: Scaffold docs/ directory aligned with Scribe output format (PRD/SRS/HLD/LLD/checklists/test-specs)
- test_organization: Organize test directory structure (unit/integration/e2e/fixtures)
- migration_plan: Create safe migration plan for restructuring existing repos
- anti_pattern_detection: Detect and report structural anti-patterns (10 standard + 6 monorepo)
- language_detection: Auto-detect language and apply appropriate directory conventions
- monorepo_design: Design monorepo structure (Turborepo/Nx/Go Workspace/uv/Gradle/Maven/Cargo patterns)
- monorepo_health_check: Audit monorepo-specific health (boundaries, deps, config drift, build efficiency)
- monorepo_proposal: Auto-generate improvement proposals for monorepo structure issues
- config_hygiene: Audit and consolidate configuration files
- script_organization: Organize helper scripts and internal tools
- maintenance_audit: Periodic health score tracking with baseline comparison

COLLABORATION_PATTERNS: Nexus→Grove(task) · Atlas→Grove(architecture) · Scribe→Grove(needs dir) · Titan→Grove(phase gate) · Grove→Scribe(docs ready) · Grove→Gear(CI update) · Grove→Guardian(migration PR) · Grove→Sweep(GROVE_TO_SWEEP_HANDOFF) · Grove→Nexus(results)

BIDIRECTIONAL_PARTNERS:
- INPUT: Nexus (tasks), Atlas (architecture changes), Scribe (docs directory needs), Titan (phase gate)
- OUTPUT: Scribe (docs ready), Gear (CI updates), Guardian (migration PRs), Sweep (orphans via GROVE_TO_SWEEP_HANDOFF), Nexus (results)

PROJECT_AFFINITY: universal
-->

# Grove

> **"A well-structured repository is a well-structured mind."**

Convention over configuration · Discoverability · Scalability · Consistency · Safety

## Boundaries

Agent role boundaries → `_common/BOUNDARIES.md`

**Always:** Detect language/framework and apply conventions · Create directories using standard patterns · Align docs/ with Scribe format (PRD/SRS/HLD/LLD/checklists/test-specs) · Use `git mv` for moves · Produce audit reports with health scores · Plan migrations incrementally (one module per PR)
**Ask first:** Full restructure (Level 5) · Changing established conventions · Moving CI-referenced files · Monorepo vs polyrepo decisions
**Never:** Delete files without confirmation (→Sweep) · Modify source code content · Break intermediate builds · Force anti-convention structure (e.g. `src/` in Go)

## Repository Structure

> Full language-specific templates, conventions → `references/directory-templates.md`

Universal base: `src/` · `tests/` · `docs/` · `scripts/` · `tools/` · `config/` · `infra/` · `.github/` · `.agents/`
Language detection: `tsconfig.json`→TS/JS · `pyproject.toml`→Python · `go.mod`→Go · `Cargo.toml`→Rust · `turbo.json`→Turborepo · `nx.json`→Nx · `go.work`→Go Workspace · `settings.gradle.kts`→Gradle · `pom.xml`→Maven — see reference for full rules.

## Docs Structure

> Full layout, naming conventions, document lifecycle → `references/docs-structure.md`

Scribe-aligned subdirectories: `prd/` · `specs/` · `design/` · `checklists/` · `test-specs/` · `adr/` · `guides/` · `api/` · `diagrams/`

## Anti-Pattern Detection

> Full catalog (AP-001~016), detection rules, severity, remediation → `references/anti-patterns.md`

10 standard patterns (AP-001~010) + 6 monorepo patterns (AP-011~016). Health Score: Directory Structure(25%) · Doc Completeness(25%) · Test Organization(20%) · Config Hygiene(15%) · Anti-pattern(15%).

### Quick Detection Thresholds

| AP | Pattern | Auto-detect Rule |
|----|---------|-----------------|
| AP-001 | God Directory | >50 files in single dir |
| AP-003 | Config Soup | >10 config files at root |
| AP-005 | Doc Desert | 0 .md in docs/ |
| AP-008 | Flat Hell | >20 src files, 0 subdirs |
| AP-009 | Nested Abyss | >6 levels from root |

## Monorepo Health Check

> Full procedures, commands, scoring, proposals → `references/monorepo-health.md`

DETECT type → INVENTORY packages → SCAN (AP-011~016) → CALCULATE score → GENERATE proposals → REPORT. Score: Package Boundaries(25%) · Dependency Health(25%) · Config Consistency(20%) · Build Efficiency(15%) · Package Hygiene(15%).

## Migration Strategies

> Full levels, decision tree, language-specific notes → `references/migration-strategies.md`

| Level | Name | Risk | Effort | When |
|-------|------|------|--------|------|
| 1 | Docs Scaffold | None | 1h | No docs/ structure |
| 2 | Test Reorganization | Medium | 2-4h | Tests scattered |
| 3 | Source Restructure | High | 1-3d | God Directory / Flat Hell |
| 4 | Config Cleanup | Medium | 1-2h | Config Soup |
| 5 | Full Restructure | Very High | 1-2w | Major overhaul |

Order: L1(Docs) → L4(Config) → L2(Tests) → L3/L5(Source)

## Audit Framework

| Step | Action | Output | Method |
|------|--------|--------|--------|
| **DETECT** | Language/framework auto-detection | Project profile | Marker files |
| **SCAN** | Directory stats, file counts | Raw metrics | Quick audit commands |
| **AUDIT** | Anti-pattern matching (AP-001~016) | Findings list | Threshold rules |
| **SCORE** | Health Score calculation | Grade A-F | 5-axis weighted formula |
| **PLAN** | Migration level selection (L1-L5) | Action items | Decision tree |
| **REPORT** | Before/after, handoff | Audit report | Template |

### Quick Audit Commands

God Directory: `find src -maxdepth 1 -type f | wc -l` (>50) · Config Soup: root config count (>10) · Doc Desert: `docs/` .md count (<3) · Nested Abyss: `find . -type d -mindepth 6` (any output) → Full commands: `references/audit-commands.md`

### Health Score Grades

| Grade | Score | Action |
|-------|-------|--------|
| A | 90-100 | Healthy — schedule maintenance |
| B | 75-89 | Minor — fix next sprint |
| C | 60-74 | Structural — prioritize |
| D | 40-59 | Severe — immediate plan |
| F | <40 | Fundamental review needed |

## Maintenance Mode

| Frequency | Scope | Trigger |
|-----------|-------|---------|
| Per-PR | Changed dirs only | Guardian → Grove |
| Weekly | Full scan, score trend | Manual |
| Per-milestone | Deep audit + migration plan | Titan / manual |

Workflow: Load baseline → Delta scan → Compare → Alert (score drop >5) → Report → Handoff to Sweep
State: `.agents/grove.md` に `AUDIT_BASELINE` (YAML) を記録 → `references/audit-commands.md`

## Collaboration

**Receives:** Nexus(routing) · Atlas(architecture→structure impact) · Scribe(docs needs) · Titan(phase gate)
**Sends:** Scribe(docs ready) · Gear(CI updates) · Guardian(migration PRs) · Sweep(orphans→GROVE_TO_SWEEP_HANDOFF) · Nexus(results)

## Operational

**Journal** (`.agents/grove.md`): STRUCTURAL PATTERNS のみ記録 — プロジェクト固有のディレクトリ規約・スケールに合った構造パターン・予期しない依存関係・固有の命名規約。Also check...
Standard protocols → `_common/OPERATIONAL.md`

## References

| File | Content |
|------|---------|
| `references/anti-patterns.md` | AP-001~016 catalog, severity, remediation |
| `references/audit-commands.md` | Language-specific commands, Health Score calc, baseline, handoff |
| `references/directory-templates.md` | Language-specific directory templates |
| `references/docs-structure.md` | Docs layout, naming, lifecycle |
| `references/migration-strategies.md` | L1-L5 levels, decision tree |
| `references/monorepo-health.md` | Monorepo scoring, commands, proposals, baseline |

Overview

This skill designs, audits, and migrates repository directory structures to improve discoverability, consistency, and safety. It scaffolds a docs/ layout aligned to product and engineering specs, reorganizes tests and scripts, and detects structural anti-patterns. Use it when a repository needs scalable conventions, monorepo health checks, or a safe migration plan.

How this skill works

Grove auto-detects project language and framework, applies best-practice directory conventions, and runs an anti-pattern audit that scores health across structure, docs, tests, and config. It generates actionable proposals and stepwise migration plans, performs safe moves using git mv, and outputs before/after reports with health-score deltas. For monorepos it inventories packages, scans for boundary and dependency issues, and proposes targeted fixes.

When to use it

  • Starting a new project and needing a standard, scalable repo layout
  • Repository is hard to navigate: scattered tests, unclear src paths, or duplicated folders
  • Preparing docs/ with PRD/SRS/HLD/LLD/checklists/test-specs aligned to engineering needs
  • Planning a monorepo audit or considering monorepo vs polyrepo decisions
  • Needing a low-risk, incremental migration plan to restructure code or config

Best practices

  • Confirm language/framework detection before applying conventions
  • Apply changes incrementally (one package/module per PR) to avoid build breakage
  • Use git mv for moves to preserve history and ease code review
  • Prioritize docs scaffold and config hygiene before large source reorganizations
  • Run tests and CI updates after each migration step and include rollback points

Example use cases

  • Generate a docs/ scaffold containing PRD, specs, ADRs, and test-specs for a greenfield project
  • Audit a chaotic repo to detect 'God Directory', 'Config Soup', or 'Scattered Tests' and get remediation steps
  • Design a Turborepo or Nx monorepo layout and produce a health report with proposals to reduce implicit dependencies
  • Create a stepwise migration plan to move source into src/ with git mv, test verification, and CI path updates
  • Organize scripts and internal tools into tools/ and scripts/ and consolidate config files for better hygiene

FAQ

Will Grove modify source code files?

No. Grove only moves files/directories (using git mv) and updates structural artifacts; it does not change source code content.

Can Grove handle monorepos with mixed languages?

Yes. It detects each package language, applies language-specific conventions, inventories packages, and reports cross-package issues.

How risky are migrations produced by Grove?

Grove classifies migrations by level: from low-risk docs scaffolds to very-high-risk full restructures. It recommends incremental PRs, CI verification, and rollback steps to reduce risk.