groundwork

Groundwork

A comprehensive skills library for Claude Code, consolidating proven techniques for planning, design, TDD, debugging, collaboration, and problem-solving.

Installation

Via Marketplace

First, add the Groundwork marketplace:

claude plugin marketplace add https://github.com/etr/groundwork-marketplace

Then install the plugin:

claude plugin install groundwork

Update via Marketplace

claude plugin marketplace update groundwork-marketplace

claude plugin update groundwork

Manual Installation

cd ~/.claude/plugins
git clone https://github.com/etr/groundwork.git

Or use the installer provided with the codebase.

Other Platforms (Experimental)

Warning: Installation on platforms other than Claude Code is experimental. Skills and agents are automatically transformed to work without Claude Code's plugin system, but some features (hooks, slash commands, skill chaining) may not work identically. Use at your own risk.

Groundwork skills and agents can be installed into other AI coding tools using the included installer script. The installer transforms skill content to remove Claude Code-specific constructs and adapts the format for each target.

Supported Targets

Target	Flag	Description
Codex CLI	--codex	Agents are installed as skills with a review- prefix
OpenCode	--opencode	Agents are installed as standalone agent files
Kiro	--kiro	Agents use JSON config + prompt file pairs

Installation

Clone the repository and run the installer:

git clone https://github.com/etr/groundwork.git
cd groundwork

Install globally (available in all projects):

./install-skills.sh --codex --global

Install for the current project only:

./install-skills.sh --opencode --project

You can install to multiple targets at once:

./install-skills.sh --codex --opencode --kiro --global

Installer Options

Option	Description
--global	Install to user-level config directory
--project	Install to current project directory
--force	Overwrite existing files
--dry-run	Preview actions without making changes
--skills-only	Install only skills (skip agents)
--source DIR	Groundwork source directory (default: auto-detect)

What Gets Installed

• Skills — Workflow definitions (planning, TDD, debugging, etc.) are installed with a groundwork- prefix. On OpenCode, skill dependencies are automatically inlined as appendix sections.
• Agents — Verification and review agents (code quality, security, architecture alignment, etc.) are installed in each target's native agent format.
• Hooks — Not installed automatically. Event-driven automations (session start, pre-compact, commit alignment) require manual setup for each tool.
• Commands — Not applicable. Other tools discover skills directly by name rather than through slash commands.

Limitations

• Hooks (SessionStart, PreCompact, PostToolUse) are not portable and must be configured manually for each tool
• On OpenCode, complex multi-skill workflows may lose interactivity since skill dependencies are inlined as static appendix sections rather than invoked at runtime
• Update checking is not available outside Claude Code

Verify Installation

Restart Claude Code or start a new session. You should see:

• Start typing /groundwork:. It should show groundwork commands available

Run /groundwork:groundwork-check to validate the plugin installation.

Dependencies

• Required: node, python3
• Optional: gh (GitHub CLI for PR commands)

Windows Users

Groundwork requires a Unix-like shell environment. Windows users should use one of:

• WSL (Windows Subsystem for Linux) - Recommended
• Git Bash - Included with Git for Windows

The plugin's shell scripts (.sh files) use bash and won't work directly in PowerShell or CMD.

Troubleshooting Windows:

Issue	Solution
"bash not found"	Install Git Bash or WSL
Hook scripts fail	Run Claude Code from WSL/Git Bash terminal
Path errors	Use forward slashes in paths, not backslashes
Line ending issues	Configure git: git config --global core.autocrlf input

Quick Start

Greenfield Project

Full planning-to-implementation workflow:

/groundwork:design-product           # Define requirements (PRD with EARS format)
/groundwork:design-architecture      # Design technical approach and decisions
/groundwork:ux-design                # Establish design system (for UI projects)
/groundwork:create-tasks             # Generate implementation tasks
/groundwork:work-on-next-task        # Start executing tasks with TDD

Quick Feature