Groundwork

Groundwork is a Claude Code-first onboarding and delivery kit. Its /onboard command scans a new project and equips it with accurate guidance, validation-aware commands, specialist agents, and a complete document-driven delivery workflow. It turns the repository into a ready-to-ship Claude workspace where Send It and Superpowers can carry work from idea through researched, tested, reviewed delivery.

The discovery model is intentionally portable so Codex and other coding-agent adapters can be added later. The current installer and generated skills support Claude Code.

Generated output reflects whatever is actually in the target repo — nothing is assumed. Ticket/URL examples in this README use neutral placeholders (PROJ-123, your-org.atlassian.net, acme). Optional delivery hooks (ship, security-review, deploy-verify) are opt-in via .claude/onboard-config.json — see the onboard skill's send-it-discovery.md — never guessed from filenames.

Quick start

unzip groundwork.zip && cd groundwork
./install.sh

Claude Code must already be installed. The default installer copies Groundwork's skills and agents, preserves any working Obra or official Superpowers provider, and installs and verifies the official provider only when none exists. Restart Claude Code, then inside a project:

/onboard                           # complete Groundwork workspace
/onboard --dry-run                 # complete preview; no writes
/onboard --send-it                 # maintenance: regenerate Send It only
/onboard --enable-mcp              # complete install + relevant project MCP config
/onboard --enable-hooks            # complete install + Groundwork hooks
/onboard --no-worktrees            # render Send It with in-place branches
/onboard --send-it --include-global-claude  # explicit, narrow user-global guidance opt-in

--send-it cannot be combined with --enable-mcp or --enable-hooks; those overlays require a normal /onboard run.

/onboard creates CLAUDE.md when absent and updates only a marked generated section when it already exists. Native /init remains available as Claude's lightweight guidance generator, but Groundwork does not require it.

Optional packs:

./install.sh --extras=browser   # agent-browser
./install.sh --extras=design    # UI styling, UX, design-system
./install.sh --extras=all       # all optional packs
./install.sh --optional-tools   # optional supporting CLIs

Existing skills/agents are skipped by default. Use --force to overwrite with timestamped backups. The installer reports whether an existing copy is current or differs from the pack. Run ./install.sh --dry-run to preview the selected pack.

To package the tracked, ignore-respecting source for a release:

git archive --format=zip --prefix=groundwork/ --output=groundwork.zip HEAD

Validate Groundwork changes

The repository's declared validation contract is exactly:

./tools/validate-pack.sh
./install.sh --dry-run

Do not infer additional required gates from installed tools or file types.

One complete onboarding path

A normal /onboard run generates project guidance, narrow settings, core project-local skills, agents and commands, Send It, worktree-aware delivery, architecture and infrastructure documentation, the complete delivery chain, self-validation, and a deterministic completion ledger. There is no setup-level choice to make.

Generated .claude/ output is project-local and may be intentionally gitignored by a target repository. Review it with an ignore-aware command such as git status --short --ignored .claude/ or direct file inspection; normal Git status may not display it.

Generated settings pre-authorize exact detected checks and read-only inspection only. They do not grant arbitrary interpreter wildcards, unrestricted Git/GitHub access, or mutating repository commands.

Use /onboard --send-it only to maintain an existing project-specific delivery skill. MCP configuration, hooks, push, PR/MR creation, and other external writes require explicit opt-in or confirmation.

Every writing onboarding mode preflights Superpowers before writing project files. If it is missing, onboarding stops with installation instructions; /onboard itself does not mutate user-global plugin state. ./install.sh owns dependency provisioning.

How the workflow fits together

Groundwork combines focused skills into a document-driven path. Each skill handles one kind of work and can be used independently; together they move from clarifying the problem to understanding the code, shaping a design, planning the change, and carrying it through implementation. Each authored stage through planning leaves a reviewable artifact in workbench/; plan-to-implementation then executes the approved plan and verifies the resulting code.

problem-to-research → research → research-to-design → design-to-outline
   → outline-to-plan → plan-to-implementation

Adversarial review (review) is a checkpoint between authored stages. Supporting skills capture decisions (decision-record), durable domain context (foundations), or multiple perspectives (debate → synthesize) without requiring the entire sequence. Optional publishing is available through publish-to-confluence. /send-it selects and combines the relevant elements for the project-specific delivery path.

Contents

Onboard + delivery

Skill	Purpose
onboard	Scan a repo and generate the complete .claude/ workspace and per-project /send-it skill.

Pipeline skills

Skill	Purpose
problem-to-research	Turn a problem statement into neutral, solution-agnostic research questions.
research	Document a codebase as-is into workbench/ for historical context.
research-to-design	Interactive technical design doc from research.
design-to-outline	High-level structure outline with vertical phases + test checkpoints.
outline-to-plan	Detailed tactical implementation plan.
plan-to-implementation	Execute an approved plan one phase at a time with verification.
review	Bounded adversarial review of any pipeline document.
decision-record	Capture an ad-hoc decision as a dated, structured snapshot.
foundations	Author a "foundation" — a sourced, dated, globally-true fact for the team's domain.
debate	Multi-perspective debate on a question/decision.
synthesize	Synthesize debate positions into consensus.

Docs

Skill	Purpose
bootstrap-docs	Create architecture/infra/changelog/backlog/CLAUDE.md for a codebase.
update-docs	Update all project docs to match current code.
publish-to-confluence	Publish a workbench/ markdown doc to Confluence.

Sessions & capability

Skill	Purpose
checkpoint / load / sessions	Save / restore / list named session checkpoints.
capability-loop	Continuous improvement loop (research → architect → debate → build → validate → release).
triage	Verify issue claims against the actual code.

Optional UI / design pack

Skill	Purpose
ui-styling	shadcn/ui + Tailwind component & theming patterns. Install with --extras=design.
ui-ux-pro-max	UI/UX intelligence: styles, palettes, font pairings, chart types, UX guidelines. Install with --extras=design.
design-system	Three-layer token architecture, component specs, slide generation. Install with --extras=design.

Optional browser pack

Skill	Purpose
agent-browser	Browser-automation CLI for agents. Install with --extras=browser.

Shared

• snippets-shared-by-skills/ — common fragments (source-fetchers, permalinks, foundations-preamble) referenced by multiple workflow skills. Keep alongside the skills.

Subagents (agents/ → ~/.claude/agents/)

codebase-locator, codebase-analyzer, codebase-pattern-finder (code discovery), workbench-locator, workbench-analyzer (prior-artifact discovery), substance-reviewer, readability-reviewer (used by review and the design/plan loops).

Dependencies installed

• Plugin (required): superpowers — provides superpowers:brainstorming, :test-driven-development, :systematic-debugging, :verification-before-completion, and :using-git-worktrees, which generated Send It invokes. Groundwork uses plan-to-implementation instead of superpowers:executing-plans to avoid duplicate execution. Upstream: github.com/obra/superpowers; available via anthropics/claude-plugins-official and provisioned by the default installer when needed.
• CLIs (optional): gh (GitHub) and agent-browser (browser skill).
• MCP (optional): github and atlassian use user authentication; shadcn and chrome-devtools are local stdio tools. See install/mcp.reference.json. No credentials are bundled.

Safety notes

• User-global CLAUDE.md content is not embedded into project output by default.
• --include-global-claude is the only global-guidance opt-in and includes only ~/.claude/CLAUDE.md; review the result before committing it.
• MCP setup is report-only unless explicitly selected; credential-shaped placeholders are not written.
• The installer ensures Superpowers by default; optional global CLIs require --optional-tools.
• Existing skills/agents are preserved unless --force is used.

License and third-party components

Groundwork's original materials are licensed under Apache-2.0; see LICENSE and NOTICE. PROVENANCE.md classifies the original and third-party component boundaries. The optional UI skills retain their MIT component licenses, agent-browser retains its Apache-2.0 attribution, and bundled fonts remain under their adjacent OFL notices. Those component terms remain applicable and are not replaced by the project license.