grove-cli 0.1.2

AI-powered development toolkit with built-in quality assurance: Spec-Driven Development × TDD × AI Auto-Review

🌳 Grove

AI-Powered Development with Built-in Quality Assurance

Spec-Driven Development × TDD × AI Auto-Review = High-Quality Software, Fast

日本語

---

🎯 What is Grove?

Grove is a spec-driven development toolkit powered by AI agents.

Traditional development requires manual "code → review → fix" cycles, which are time-consuming and error-prone.

Grove automates from specification to implementation, integrating TDD workflows and AI auto-review to generate high-quality code at speed.

Why Grove?

✅ Specs Stay Current: Direct code generation from specs keeps documentation and code in sync ✅ Quality Guaranteed: TDD + 3-layer AI review for automatic quality checks ✅ Fast Feedback: Background parallel execution ~28% faster ✅ AI Collaboration: Cross-check with multiple AI agents ✅ Multi-language: Full Japanese and English support

🚀 Three Key Features

1. 🧪 t-wada Style TDD Integration

Test-Driven Development enforced for every task:

For each task:
  Red      → Confirm test failure
  Green    → Minimal implementation to pass
  Refactor → Improve while keeping tests green
  Review   → AI automated verification

Formalizes Japanese TDD tacit knowledge for AI execution.

2. 🔍 3-Layer AI Review System

Implementation → Self Review → Cross Review quality assurance:

Layer	Executor	Timing	Purpose
Layer 1: Implementation	AI Agent	During implementation	Code generation with TDD workflow
Layer 2: Self Review	Same AI Agent	Immediately after (background)	8-point auto-verification + Auto-Fix
Layer 3: Cross Review	Different AI Agent	As needed	Additional verification from different perspective

Self Review Automation:

T001 completed → Self Review launch (background)
T002 completed → Self Review launch (background)
T003 completed → Self Review launch (background)
      ↓
All complete → Report generation → Auto-Fix (max 3 attempts)

8-Point Verification Checklist:

1. ✅ Specification Compliance
2. ✅ Tech Stack Adherence
3. ✅ Task Completeness
4. ✅ Test Coverage
5. ✅ Error Handling
6. ✅ Security
7. ✅ Performance
8. ✅ Code Quality

Scoring: 0-100 points (Critical: -30, High: -20, Medium: -10, Low: -5) Pass Criteria: 80+ points

3. ⚡ Background Parallel Execution

Traditional Sequential:

Implement → Verify (wait) → Implement → Verify (wait) → ...

Grove Parallel:

Implement → Verify (background)
    ↓
Implement → Verify (background)
    ↓
Implement → Verify (background)
    ↓
All complete → Collect results → Fix

Reduces wait time and improves development speed.

📦 Installation

Install from PyPI (Recommended)

# Stable release from PyPI
uv tool install grove-cli

Install from GitHub (Development Version)

# Latest development version
uv tool install grove-cli --from git+https://github.com/cardene777/grove.git

Initialize Project

# New project
grove init my-app --ai claude --lang en

# Existing project
grove init . --ai claude --lang en

# Or
grove init --here --ai claude --lang en

Upgrade

# Upgrade PyPI version
uv tool install grove-cli --upgrade

# Upgrade GitHub version
uv tool install grove-cli --force --from git+https://github.com/cardene777/grove.git

🎬 Usage

Basic Workflow

# Launch AI agent and navigate to project directory
# The following commands become available

# 1. Define project principles
/grove.constitution Create principles focused on code quality, testing standards, and performance

# 2. Create feature specification
/grove.specify Build a task management application with projects, tasks, and Kanban boards

# 3. (Optional) Frontend design specifications
/grove.design Create design system with design tokens, components, and layouts

# 4. Create technical implementation plan
/grove.plan Use React + TypeScript, Node.js, and PostgreSQL

# 5. Break down into tasks
/grove.tasks

# 6. Execute implementation (TDD + Self Review auto-run)
/grove.implement

# 7. (Optional) Cross review (run with different AI)
/grove.review

# 8. (Optional) Auto-fix issues
/grove.fix

Execution Example

T001 Implementation completed.
🔄 T001 Self Review launched in background (job: a703da0)
   Report will be saved to: reports/self-review/task-T001.md

T002 Implementation completed.
🔄 T002 Self Review launched in background (job: aa59562)
   Report will be saved to: reports/self-review/task-T002.md

⏳ Waiting for 2 verification agents to complete...
✓ All verification agents completed

Parsing reports...
✓ T001: PASS (Score: 95/100)
✗ T002: FAIL (Score: 65/100, 3 issues)

🔧 Auto-fixing T002...
✓ T002 Auto-Fix SUCCESS (Score: 85/100)

Self Review completed.

🤖 Supported AI Agents

17+ AI agents supported:

AI Agent	Support	Notes
Claude Code	✅	Recommended - Full background Self Review support
Cursor	✅
GitHub Copilot	✅
Codex CLI	✅
Gemini CLI	✅
Windsurf	✅
12+ others	✅	Qoder, Amp, Auggie, CodeBuddy, IBM Bob, Jules, Kilo Code, opencode, Qwen, Roo, SHAI, etc.

See Supported Agents for details.

📋 Commands

Core Commands (Development Flow)

Command	Description
/grove.constitution	Create project principles and development guidelines
/grove.specify	Define feature specifications (requirements, user stories)
/grove.plan	Create technical implementation plan (tech stack, architecture)
/grove.tasks	Break down into tasks (with TDD workflow)
/grove.implement	Execute implementation (TDD + Self Review auto-run)

Quality Assurance Commands

Command	Description
/grove.review	Execute AI review (Self/Cross Review auto-detected)
/grove.fix	Auto-fix review issues (TDD approach)

Optional Commands

Command	Description
/grove.clarify	Clarify underspecified areas
/grove.design	Create frontend design specifications
/grove.analyze	Cross-artifact consistency analysis
/grove.checklist	Generate custom quality checklists

🔍 How Self Review Works

1. Background Launch

Upon implementation completion, Verification Agent launches in background:

Task(
    description="Verify task T001",
    prompt="...",
    subagent_type="verification-agent",
    run_in_background=True  # Background execution
)

2. Autonomous Verification & Report Generation

Verification Agent auto-executes:

1. Load Context: spec.md, plan.md, tasks.md
2. Read Implementation: Task-specified files
3. 8-Point Verification: Checklist-based verification
4. Score Calculation: 0-100 points (severity-based penalties)
5. Generate Report: Markdown format
6. Save File: reports/self-review/task-{ID}.md

3. Report Format

# Task T001 Verification Report

**Date:** 2025-12-21 10:30:00
**Task ID:** T001
**Description:** User authentication implementation
**Phase:** Phase 1

---

## 1. Summary

| Item   | Value        |
| ------ | ------------ |
| Score  | 85/100       |
| Status | **PASS**     |
| Issues | 1            |

---

## 2. Verification Checklist

- [x] Specification Compliance: PASS
- [x] Tech Stack Adherence: PASS
- [x] Task Completeness: PASS
- [x] Test Coverage: PASS
- [x] Error Handling: FAIL
- [x] Security: PASS
- [x] Performance: PASS
- [x] Code Quality: PASS

---

## 3. Verification Results

##### Issue 1

| Item     | Details             |
| -------- | ------------------- |
| Severity | Medium              |
| Location | `src/auth.py:42`    |

- **Description**: Insufficient error handling for login failure
- **Cause**: Missing try-except block
- **Recommended Fix**: Add exception handling
- **Evidence**: [code snippet]

---

## 4. Conclusion

Task T001 verification completed. Score: 85/100

1 minor issue found, but meets pass criteria (80+).

4. Auto-Fix

Failed tasks automatically fixed:

🔧 Auto-fixing T002 (Score: 65/100, 3 issues)...

Issue 1 (Critical): No password hashing
  Red:    Add test
  Green:  Implement bcrypt
  Refactor: Verify test ✓

Issue 2 (High): No input validation
  Red:    Add test
  Green:  Implement validation
  Refactor: Verify test ✓

Issue 3 (Medium): Insufficient error handling
  Red:    Add test
  Green:  Add exception handling
  Refactor: Verify test ✓

Re-verification: Score 85/100 (0 issues) ✓

Up to 3 auto-fix attempts.

🌍 Multi-language Support

Full Japanese and English support:

# Japanese
grove init my-app --ai claude --lang ja

# English
grove init my-app --ai claude --lang en

Templates, commands, and reports generated in selected language.

📚 Documentation

• Grove Guide (Japanese) - Comprehensive guide
• Development Methodology - Full spec-driven process
• Installation Guide - Setup instructions
• Quick Start - Get started in 5 minutes
• Local Development - Contributing

🛠️ Requirements

• OS: Linux / macOS / Windows
• AI Agent: One of the supported agents
• Python: 3.11+
• Package Manager: uv
• Version Control: Git

💡 FAQ

Q: How is Grove different from Spec Kit?

A: Grove extends Spec Kit with powerful features:

Feature	Spec Kit	Grove
Spec-Driven Development	✅	✅
TDD Integration	❌	✅ t-wada style
Self Review	❌	✅ Background parallel execution
Cross Review	❌	✅ Multi-AI support
Auto-Fix	❌	✅ TDD approach
Multi-language	❌	✅ Japanese/English
Verification Agent	❌	✅ Claude Code support

Q: Which AI agent is recommended?

A: Claude Code is recommended. Full support for background Self Review and Verification Agent.

Other AI agents work but Self Review runs synchronously.

Q: Can I use with existing projects?

A: Yes. Run grove init . --ai claude or grove init --here --ai claude in your project directory.

Q: Can I skip review?

A: Yes. Use /grove.implement --skip-self-review to skip Self Review.

However, not recommended for quality assurance.

🤝 Contributing

Pull requests and issue reports welcome!

See CONTRIBUTING.md for details.

💬 Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Issues
• Questions/Discussion: GitHub Discussions

🙏 Acknowledgements

Grove is built on the work of these projects and individuals:

Spec Kit (GitHub):

• Den Delimarsky
• John Lam

Grove Extensions:

• Cardene

TDD Methodology:

• t-wada - Test-Driven Development

Thank you to all contributors.

📄 License

Released under the MIT License. See LICENSE for details.

---

🌳 Grove - High-Quality Development Toolkit for the AI Era
Built with ❤️ by the Grove community