groundwork — Claude Code plugin: requirements to validation workflow

# Groundwork

A comprehensive skills library for Claude Code and Codex, consolidating proven techniques for planning, design, TDD, debugging, collaboration, and problem-solving. ZCode is also supported (installer export and managed marketplace); experimental exports are available for OpenCode, Kiro, and Pi.

## Installation

### Via Marketplace

First, add the Groundwork marketplace:

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

Then install the plugin:

```bash
claude plugin install groundwork
```

#### Update via Marketplace

```bash
claude plugin marketplace update groundwork-marketplace

claude plugin update groundwork
```

### Manual Installation

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

Or use the installer provided with the codebase.

### Multi-target Installer

Groundwork supports Claude Code, Codex, and ZCode (both the installer export and the managed marketplace). Exports for OpenCode, Kiro, and Pi are experimental: the installer transforms Claude Code-specific constructs for those harnesses, but hooks, invocation, and skill chaining may not behave identically.

Two boundaries apply to the experimental exports. First, **source/install parity**: the installer ships every runtime helper the exported skills reference (enforced by tests), so helper behavior matches the source tree — but features that depend on Claude Code hooks (session-start bindings, template-variable resolution, commit-alignment checks) run only where the target supports an equivalent (ZCode's filtered hook events; the Pi extension's own event handlers). Second, **hookless selection limitation**: on harnesses without hooks, monorepo project selection is not pinned per chat — re-select the active project in each session before running project-scoped skills.

The included installer adapts Groundwork skills and agents to each target's native format. Claude Code users should normally use the marketplace; Codex users should use the installer.

#### Supported Targets

| Target | Flag | Maturity | Description |
|--------|------|----------|-------------|
| Claude Code | `--claude-code` | Supported | Recommends the marketplace install; an explicit opt-in allows a full plugin copy with no transformation |
| [Codex CLI](https://github.com/openai/codex) | `--codex` | Supported | Installs skills, native custom-agent TOML files with Codex model and reasoning settings, and the external task runner |
| [OpenCode](https://github.com/opencode-ai/opencode) | `--opencode` | Experimental | Installs transformed skills and standalone agent files |
| [Kiro](https://kiro.dev) | `--kiro` | Experimental | Installs transformed skills and JSON config + prompt file pairs for agents |
| Pi | `--pi` | Experimental | Installs transformed skills, `review-`prefixed agent skills, and a pre-built TypeScript extension (`pi-extension/`) |
| ZCode | `--zcode` | Supported | Installs transformed skills to `~/.zcode/skills/` (or `.zcode/skills/`); agents become `review-`prefixed skills |
| ZCode (marketplace) | `--zcode-plugin` | Supported | Plugin flavor for the managed marketplace: native `agents/*.md`, GLM model wording, filtered hooks — packaged by `build-zcode-marketplace.sh` |

##### Codex Agent Conversion

Codex agents are written to `.codex/agents/*.toml` for project installs (or
`~/.codex/agents/*.toml` globally). Claude model metadata maps as follows:

| Claude agent model | Codex model override |
|--------------------|----------------------|
| `sonnet` | `gpt-6.1-sol` |
| `opus[1m]` | `gpt-6.1-sol` |
| `inherit` or absent | No override; inherit the active Codex model |

Role-specific policy overrides that generic mapping. In particular, the
`task-executor` is exported as `gpt-6.1-sol` at high effort so implementation
does not inherit a weaker orchestration model.

Supported effort values (`low`, `medium`, `high`, and `max`) are preserved as
`model_reasoning_effort`; an absent effort is omitted. Unsupported model or
effort values stop the install with an explicit error so a silent fallback
cannot select an unintended model.

#### Model Overrides

Groundwork's model policy can be translated at install time without editing the
Claude-native source skills. Pass a JSON file with `--model-override`; the
option applies to every install target (`--codex`, `--claude-code`, `--zcode`,
`--zcode-plugin`, `--opencode`, `--kiro`, `--pi`), alone or combined:

```bash
./install-skills.sh --codex --global --force \
  --model-override model-overrides/glm.json
```

The file has three logical tiers:

| Tier | Current default | Groundwork meaning |
|------|-----------------|--------------------|
| `light` | `gpt-6-luna` / Claude `haiku` | monitoring and lightweight work |
| `balanced` | `gpt-6.1-sol` / Claude `sonnet` | routine orchestration and bounded work |
| `deep` | `gpt-6.1-sol` / Claude `opus[1m]` | implementation, validation, security, and escalation |

Codex uses Sol 6.1 for both balanced and deep work, and Luna 6 for light work.
Reasoning effort policies are unchanged; custom overrides retain separate tiers.

A custom file may translate any subset of tiers and optionally force all
installer-controlled reasoning policies to one effort:

```json
{
  "effort": "max",
  "translation": {
    "light": "glm-5.3-flash",
    "balanced": "glm-5.3-flash",
    "deep": "glm-5.3"
  },
  "skills": {
    "validate": "glm-5.3"
  },
  "agents": {
    "task-executor": "glm-5.3"
  }
}
```

`translation` supplies the default actual model. Exact `skills` and `agents`
entries are exceptions and use canonical Groundwork IDs such as `validate` and
`task-executor`—not installed names such as `groundwork-validate`. A skill with
no installer-controlled model directive continues inheriting the harness's
active model; the installer rejects an exact override that would have no
effect.

The override rewrites the model recommendations in every exported skill and
agent body, whichever names the target uses: the Codex export's tier models
(`terra`, `sol`, …), the Claude source names kept by the Claude Code copy and
the OpenCode/Kiro/Pi exports (`Sonnet`, `opus[1m]`, …), and the ZCode exports'
GLM family names (`GLM`, `GLM-Flash` — so a ZCode user can pin concrete GLM
versions). Codex additionally resolves agent model/effort directives through
the override; on Claude Code the override is applied to the freshly copied
plugin's skills and agents.

The builtin Codex conversion itself is versioned as
`lib/codex-model-policy.json` and is the base policy for every install. A
`--model-override` file is only an overlay; it does not replace or deselect the
builtin validation rules.

The bundled `model-overrides/glm.json` uses only `glm-5.3` and
`glm-5.3-flash`, both at `max` effort; Flash handles both `light` and
`balanced`, while `glm-5.3` is reserved for `deep`. With a harness itself
configured for a GLM model, it prevents Groundwork's exported agent and
subagent directives from selecting built-in models that do not exist there.
It does not change unrelated skills, custom agents, or user configuration.

Existing files changed by an override require `--force` (except the Claude
Code copy, which is written fresh on every install). Use `--dry-run` to
validate the file and preview its effective values without writing output.

When installing Codex agents, the installer also removes the exact legacy
`.codex/skills/review-<bundled-agent>/SKILL.md` file for each bundled Groundwork
agent. It does not use a wildcard: unrelated `review-*` skills and any sidecar
files are preserved, and an empty legacy directory is removed.

#### ZCode Notes

There are two ZCode install paths.

**Managed marketplace (recommended).** A generated marketplace lives on the
[`zcode-marketplace` branch](https://github.com/etr/groundwork/tree/zcode-marketplace)
of this repository — the translated export packaged as a plugin with native
agents. In ZCode: **Settings → Plugin Management → Discover → `+`**, add
`etr/groundwork#zcode-marketplace`, then install **Groundwork**. Updates and
uninstall are handled by ZCode's plugin system. Rebuild the branch with:

```bash
bash build-zcode-marketplace.sh   # then push dist/zcode-marketplace to the branch
```

(CI republishes the branch automatically on every release.)

**File export.** `./install-skills.sh --zcode --global` installs transformed
skills to `~/.zcode/skills/` (`.zcode/skills/` for projects), each as a
`groundwork-<name>` directory whose frontmatter carries only `name` and
`description` (the fields ZCode honors; descriptions stay under its
1024-character limit). Because ZCode loads custom agents only from
marketplace-installed plugins, the file export ships agents as
`review-<agent>` skills and rewrites agent spawns into sub-task delegation.

Shared translation details: Claude model recommendations become concrete GLM
family recommendations — GLM with reasoning at max (GLM-Flash for the lighter
tier) — phrased as model-picker/settings actions, because ZCode has no
Claude-style `/model` or `/effort` commands. The marketplace flavor additionally
ships agents natively (`agents/*.md`, references inlined as appendices) and
hooks filtered to the seven events ZCode supports (SessionStart and PostToolUse
survive; SubagentStop and PreCompact have no ZCode equivalent).

#### Installation

Clone the repository and run the installer:

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

Install globally (available in all projects):

```bash
./install-skills.sh --codex --global
./install-skills.sh --zcode --global
```

Install for the current project only:

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

You can install to multiple targets at once:

```bash
./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) |
| `--model-override FILE` | Apply a model translation/exact-override JSON file (any target) |

#### 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. On Pi and ZCode, agents are exported as `review-`prefixed skills because those harnesses load custom agents only from plugins.
- **Hooks** — Included in the Claude Code plugin. Transformed exports do not install equivalent harness hooks automatically.
- **Invocation** — Claude Code exposes `/groundwork:<name>` slash commands. Other harnesses discover the exported `groundwork-<name>` skills using their native skill interface.

#### Cross-harness Limitations

- Claude Code hooks (`SessionStart`, `PreCompact`, `PostToolUse`) are not portable and must be configured manually in other harnesses
- On OpenCode, complex multi-skill workflows may lose interactivity since skill dependencies are inlined as static appendix sections rather than invoked at runtime
- On ZCode, review agents run as `review-`prefixed skills (inline or via general-purpose subagents) rather than native custom agents; the invocation-tier frontmatter (`disable-model-invocation`, `user-invocable`) is not honored, so every exported skill is both model- and user-invocable
- Update checking is not available outside Claude Code

### Verify the Claude Code Installation

Restart Claude Code or start a new session. You should see:
- Start typing `/groundwork:`. It should show groundwork skills available

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

## Dependencies

- **Required**: `node`, `python3`
- **Optional**: `gh` (GitHub CLI for PR workflows)

### 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

Skip formal planning and go straight to building:

```
/groundwork:build-unplanned Add user avatar upload with image resizing
```

### Monorepo Project

Set up a monorepo and start planning for a specific project:

```
/groundwork:setup-repo               # Detect monorepo, create .groundwork.yml
/groundwork:select-project           # Choose which project to work on
/groundwork:design-product           # Define requirements for selected project
```

### Existing Codebase

Analyze existing code to generate initial specifications:

```
/groundwork:design-product           # Analyzes codebase to propose PRD
```

## Skills

Every Groundwork capability is a skill. The examples below use Claude Code's slash syntax: `/groundwork:<name>` (the prefix can be omitted if no other plugin uses the same name). The other installs discover the same capabilities as `groundwork-<name>` skills. Some skills are also invoked automatically by the model when relevant, and a few low-level "library" skills are used only by other skills (not listed below).

### Planning Skills

Define what to build and how to build it.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:design-product` | `[product-name]` | Create or update PRD with EARS requirements | Starting a new project or adding features |
| `/groundwork:design-architecture` | `[feature-name]` | Design technical architecture with decision records | After PRD exists, need technical design |
| `/groundwork:swarm-design-architecture` | `[feature-name]` | Parallel adversarial architecture design with agent teams | Multiple viable tech options, need balanced comparison |
| `/groundwork:ux-design` | `[product-name]` | Establish design system — foundations, brand, UX patterns | Need visual/UX consistency for UI projects |
| `/groundwork:create-tasks` | `[filter]` | Generate implementation tasks from PRD + architecture | After specs exist, ready to plan implementation |
| `/groundwork:setup-repo` | — | Configure repo — detect single-project or monorepo | First time using Groundwork in a repo |

### Design & Engineering Techniques

Sharpen a design or de-risk an approach before committing to it.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:domain-modeling` | — | Build and maintain a pure domain glossary | Project lacks shared, agreed terminology |
| `/groundwork:design-it-twice` | — | Generate 2–3 divergent interface designs and compare on depth/locality/seam | Before committing to a non-trivial module, service boundary, or public API |
| `/groundwork:doubt-driven-development` | — | Adversarially refute the chosen approach before building | High-stakes/hard-to-reverse change — migrations, auth, payments, destructive ops |
| `/groundwork:vertical-slice` | — | Structure work as thin, end-to-end, independently-shippable slices behind a flag | Feature large enough to span multiple layers |

### Implementation Skills

Execute tasks and build features.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:work-on` | `[task-number]` | Execute a specific task with worktree isolation and TDD | Want to work on a specific task by number |
| `/groundwork:work-on-next-task` | — | Execute the next unblocked task automatically | Working through tasks sequentially |
| `/groundwork:plan-task` | `[task-number-or-description]` | Plan a task or feature without implementing | Want to review a plan before committing to implementation |
| `/groundwork:implement-task` | `[task-number-or-plan-path]` | Implement a previously planned task | Resume implementation after reviewing a plan |
| `/groundwork:just-do-it` | — | Execute all remaining tasks in dependency order | Want batch execution inside the current session |
| `/groundwork:just-do-it-swarming` | `[--parallel]` | Execute all tasks using agent teams for context isolation | Large batches where context accumulation is a concern |
| `/groundwork:build-unplanned` | `[description]` | Build feature from description — no task definitions needed | Quick feature without formal planning |
| `/groundwork:select-project` | `[project-name]` | Switch to a different project in a monorepo | Working across multiple projects |

### Debugging Skills

Investigate and resolve issues systematically.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:debug` | `[bug description]` | Systematic 5-phase debugging workflow | Investigating bugs or test failures |
| `/groundwork:swarm-debug` | `[bug description]` | Parallel hypothesis investigation with agent teams | Multiple plausible root causes, needs adversarial testing |

### Verification Skills

Validate code quality and spec alignment.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:validate` | — | Re-run 9-agent verification on current changes | Verify code quality after manual changes |
| `/groundwork:finalize-task` | `[task-id] [--project name]` | Commit, merge, and clean up a validated task worktree | Completing the workflow manually phase by phase |
| `/groundwork:check-specs-alignment` | `[context]` | Audit code alignment with PRD and architecture | Periodic drift detection |

### Review Skills

Review pull requests with multi-agent analysis. Requires `gh` (GitHub CLI).

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:review-pr` | `[PR# or URL] [--no-interactive]` | Multi-agent PR review with inline GitHub comments | Reviewing PRs before merge |

### Shipping Skills

Make a change observable and roll it out safely.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:instrument-observability` | — | Add structured logging, RED metrics, trace spans, and symptom-based alerts | While building a change, before an incident proves it was unobservable |
| `/groundwork:staged-rollout` | — | Roll out behind a feature flag with a monitoring window and written rollback plan | Before shipping anything user-facing |
| `/groundwork:ship` | — | Sequence observability + staged rollout behind a final go/no-go gate | Ready to ship a validated change to production |

### Synchronization Skills

Keep specs in sync with what was actually built. Run these at the end of a session when implementation diverged from the original plan.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:source-product-specs-from-code` | `[files...]` | Update PRD to reflect implementation changes | After product decisions during implementation |
| `/groundwork:source-architecture-from-code` | `[files...]` | Update architecture docs with new decisions | After architectural changes during implementation |
| `/groundwork:source-ux-design-from-code` | `[files...]` | Update design system with token/pattern changes | After design changes during implementation |
| `/groundwork:split-specs` | — | Convert single-file PRD into directory format | PRD has grown large (auto-triggered at 500+ lines or 15+ features) |
| `/groundwork:split-architecture` | — | Convert single-file architecture doc into directory format | Architecture doc has grown large (auto-triggered at 500+ lines or 10+ DRs) |

### Utility Skills

Plugin management and reference.

| Skill | Args | Description | When to Use |
|---------|------|-------------|-------------|
| `/groundwork:handoff` | `[focus]` | Produce a compact handoff document transferring context, state, and next objective | Ending a session or passing work to another agent |
| `/groundwork:skills` | — | List all available Groundwork skills | Discovering available capabilities |
| `/groundwork:groundwork-check` | — | Validate plugin installation | Troubleshooting issues |
| `/groundwork:groundwork-help` | — | Show all skills | Quick reference |

## Model Recommendations

Skills vary in complexity. The table below lists the minimum model tier recommended for each skill. Running a skill below its recommended tier may produce lower-quality results or hit context limits.

| Tier | Minimum Model | Skills |
|------|---------------|----------|
| **Opus (1M)** | Opus at high effort | `/groundwork:design-product`, `/groundwork:design-architecture`, `/groundwork:ux-design`, `/groundwork:create-tasks`, `/groundwork:debug`, `/groundwork:swarm-debug`, `/groundwork:swarm-design-architecture`, `/groundwork:design-it-twice`, `/groundwork:doubt-driven-development` |
| **Sonnet+** | Sonnet or Opus at high effort | `/groundwork:work-on`, `/groundwork:work-on-next-task`, `/groundwork:just-do-it`, `/groundwork:just-do-it-swarming`, `/groundwork:build-unplanned`, `/groundwork:validate`, `/groundwork:finalize-task`, `/groundwork:check-specs-alignment`, `/groundwork:review-pr`, `/groundwork:source-product-specs-from-code`, `/groundwork:source-architecture-from-code`, `/groundwork:source-ux-design-from-code`, `/groundwork:domain-modeling`, `/groundwork:vertical-slice`, `/groundwork:instrument-observability`, `/groundwork:staged-rollout`, `/groundwork:ship` |
| **Any** | No requirement | `/groundwork:setup-repo`, `/groundwork:select-project`, `/groundwork:handoff`, `/groundwork:skills`, `/groundwork:groundwork-help`, `/groundwork:groundwork-check` |

## Workflows

### Greenfield Project

Full planning through implementation with continuous synchronization:

```
/groundwork:design-product              # 1. Define requirements
/groundwork:design-architecture         # 2. Design technical approach
/groundwork:ux-design                   # 3. Establish design system (UI projects)
/groundwork:create-tasks                # 4. Generate task list
/groundwork:work-on-next-task           # 5. Execute tasks one by one (repeat)
/groundwork:source-product-specs-from-code   # 6. Sync specs if implementation diverged
/groundwork:source-architecture-from-code    # 7. Sync architecture if decisions changed
```

### Adding Features to an Existing Project

Incrementally update specs, implement, then sync:

```
/groundwork:design-product              # Update PRD with new feature requirements
/groundwork:design-architecture         # Update architecture for new components
/groundwork:create-tasks                # Generate tasks for the new feature
/groundwork:work-on-next-task           # Execute tasks
/groundwork:source-product-specs-from-code   # Sync any implementation-time decisions
```

### Plan Then Implement (Split Workflow)

Plan a task first, review the plan, then implement separately:

```
/groundwork:plan-task 4                 # Plan task 4, saves to .groundwork-plans/
# ... review the plan, adjust if needed ...
/groundwork:implement-task 4            # Implement using the saved plan
/groundwork:validate                    # Validate and fix the task worktree
/groundwork:finalize-task 4             # Commit remaining fixes, merge, and clean up
```

Also works for ad-hoc features:

```
/groundwork:plan-task "Add SSO login"   # Plan from a description
/groundwork:implement-task .groundwork-plans/FEATURE-sso-login-plan.md
```

### Quick Unplanned Feature

Skip planning entirely — go straight to TDD:

```
/groundwork:build-unplanned Add password strength indicator to signup form
```

This gathers requirements inline, implements with TDD in a worktree, runs verification agents, and merges back.

### Debugging

Systematic 5-phase investigation:

```
/groundwork:debug Login fails silently when session cookie is expired
```

Phases: Observe → Hypothesize → Predict → Test → Conclude. No fix is applied until the root cause is confirmed.

### Batch Execution

Execute all remaining tasks in dependency order inside the current conversation:

```
/groundwork:just-do-it
```

The coordinator conversation owns Plan → Implement → Validate → Finalize for every harness, delegating implementation and reviews while keeping one active task through merge and cleanup. Any user-specified task range or stop boundary limits the batch. Launch the external runner separately when you want it to own execution.

### External Task Runner

The external runner is a start-once completion harness for Claude Code, Codex, and ZCode (headless). Give it one or more implementation tasks, a range, or all remaining tasks; it creates an isolated linked worktree for each selected task and drives `plan-task → implement-task → validate → finalize-task` until the work is implemented, validated, integrated, and marked complete.

The runner is valuable when work should continue unattended. Fresh processes keep phase context focused, durable checkpoints make interrupted runs resumable, repair sessions handle recoverable failures, and verified Git handoffs prevent a model's claim of success from being treated as proof. Read-only status and logs expose phase progress, validation rounds, reviewer state, and credential-redacted diagnostics while it runs.

Delegation remains the context-isolation boundary: the executor owns implementation and test monitoring, and a separate validation coordinator owns reviewers and fixers. The root waits for completion, a concrete blocker, or a required decision; routine visibility uses runner status and heartbeats instead of periodic agent messages or duplicate test supervision.

Verification reuses the frozen acceptance baseline and valid evidence. Missing shared verification infrastructure outside the task becomes an explicitly owned dependency, not an implicit framework-building assignment; unavailable required checks remain incomplete. After two repair/closure cycles without fewer blocking invariants, validation requires an evidence-backed strategy change or an incomplete handoff. Codex exports use medium effort for routine coordination while preserving executor/reviewer effort; a headless Codex trial must explicitly pass `--coordinator-effort medium` to override the runner's configured default.

Use the runner for well-specified tasks when you want hands-off completion, repeatable validation, or a batch processed in dependency order. Use the same skills manually when requirements or architecture still need discussion, you want to approve each phase, or the change is small enough that an interactive session is simpler. The runner can commit and merge completed task work into the local base branch, so start it only when that workflow is intended.

Each phase runs in a fresh Claude Code, Codex, or ZCode process with the harness's native session persistence enabled. Groundwork passes compact receipts and verified Git state between phases; it neither disables native memory nor copies memory between harnesses.

#### Usage

```bash
node /path/to/groundwork/bin/groundwork-run.js task TASK-004 --harness claude
node /path/to/groundwork/bin/groundwork-run.js task TASK-004 TASK-009 TASK-012 --harness codex
node /path/to/groundwork/bin/groundwork-run.js task TASK-004 --harness zcode
node /path/to/groundwork/bin/groundwork-run.js all --harness codex
node /path/to/groundwork/bin/groundwork-run.js all --from TASK-010 --to TASK-025 --harness codex
node /path/to/groundwork/bin/groundwork-run.js all --harness codex --project api --dry-run
node /path/to/groundwork/bin/groundwork-run.js all --harness codex --revalidate-if-merge-conflicts
node /path/to/groundwork/bin/groundwork-run.js status TASK-005 --project api
node /path/to/groundwork/bin/groundwork-run.js logs TASK-005 --project api --tail 40 --follow
```

Run the repository's `bin/groundwork-run.js` with any supported `--harness`. Codex exports also install it at `~/.codex/groundwork-run.js` for user scope or `.codex/groundwork-run.js` for project scope. Before the first phase, the runner verifies the selected harness can actually discover Groundwork — the harness CLI must be on `PATH`, and the phase skills must be installed (Claude Code and ZCode: marketplace plugin or file export; Codex: `install-skills.sh`) — and fails with an actionable error instead of a confusing mid-run failure. ZCode headless has no plugin-dir injection and no `--output-last-message` file, so the runner invokes `zcode --prompt … --output-format stream-json` (falling back to the CLI bundled with the macOS ZCode app when no `zcode` binary is on `PATH`) and reads the final message from the stream's `result` event. The runner creates each linked task worktree before planning and runs every phase from its project root. It repeatedly chooses the lowest-numbered currently unblocked task, so dependency constraints take precedence and numeric priority breaks ties. When any phase invocation, receipt, or handoff fails, a fresh repair session receives...