tim-hub/powerball-harness/harness-setup

Harness Setup

Quick Reference

Subcommand Details

init — Project Initialization

Introduce Harness to a new project.

Generated files (user's project):

project/
├── CLAUDE.md            # Project configuration
├── .gitignore           # Standard ignore rules (harness-managed block appended)
└── .claude/
    ├── settings.json    # Claude Code permissions/sandbox/env
    ├── harness/plans.json  # Task tracking (auto-created by harness plan-cli)
    ├── memory/          # Trace archive + schemas (archive/, schemas/)
    ├── output-styles/   # Custom output styles (if any)
    ├── rules/           # Custom rules (if any)
    ├── scripts/         # Custom scripts (if any)
    └── skills/          # Custom skills (if any)
    └── settings.local.json # Local custom settings (gitignored) for user overrides

Note: Neither hooks/ nor harness.toml is generated into a user's project.

- Hooks ship inside the installed plugin (.claude-plugin/hooks.json) — Claude Code

loads them from there automatically.

- harness.toml + harness sync is a plugin-author workflow for regenerating

.claude-plugin/* files from a single TOML SSOT. User projects have no

.claude-plugin/ to regenerate, so the TOML would be an orphaned file. Users who

want unified TOML authoring for their own .claude/settings.json can opt in later

via a dedicated subcommand (future work).

Flow:

1. Run the gitignore subcommand (idempotent — calls scripts/merge-gitignore.sh)
2. Detect project type (Node.js/Python/Go/Rust/Other)
3. Generate minimal CLAUDE.md
4. Create .claude/harness/ directory (plans.json is auto-created on first harness plan-cli add-phase call)
5. Generate .claude/settings.json (permissions/sandbox/env — safe defaults)

gitignore — Harness .gitignore Block

Merges the harness-managed block into the project's .gitignore. Safe to run multiple times — skips if the marker is already present.

Implementation: `scripts/merge-gitignore.sh`

bash "${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh"
# Or with an explicit target path:
bash "${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh path/to/.gitignore"

The block ignores .claude/sessions/, logs/, settings.local.json, and states/, while force-tracking .claude/memory/, .claude/output-styles/, .claude/rules/, .claude/scripts/, .claude/skills/, and .claude/settings.json.

codex — Codex CLI Setup

Sets up the project for Codex CLI by copying Harness config templates and skills. See Codex CLI Setup Reference for full file layout and troubleshooting.

Prerequisites: Codex CLI installed (npm install -g @openai/codex)

What it does:

1. Checks that codex is installed; prints install instructions if not
2. Copies templates/codex/* → .codex/ (config.toml, rules/harness.rules, .codexignore)
3. Copies AGENTS.md to the project root
4. Copies all skills from plugin skills/ → .codex/skills/ with disable-model-invocation: true patched into each SKILL.md frontmatter
5. Overlays templates/codex-skills/ → .codex/skills/ (codex-native variants of breezing and harness-work override the generic copies)

bash "${CLAUDE_SKILL_DIR}/scripts/setup-codex.sh"

Note: Excluded from the no-args init run — requires an external @openai/codex install that should be explicit opt-in.

opencode — OpenCode Setup

Sets up the project for OpenCode by copying Harness config templates, commands, and skills.

Prerequisites: OpenCode installed (see https://opencode.ai/)

What it does:

1. Checks that opencode is installed; prints install instructions if not
2. Copies templates/opencode/opencode.json → .opencode/opencode.json
3. Copies templates/opencode/commands/ → .opencode/commands/
4. Copies AGENTS.md to the project root
5. Copies all skills from plugin skills/ → .opencode/skills/ as-is (opencode ignores unknown frontmatter fields)

bash "${CLAUDE_SKILL_DIR}/scripts/setup-opencode.sh"

Note: Excluded from the no-args init run — requires OpenCode to be installed explicitly.

duo — Codex + OpenCode Setup

Runs both codex and opencode setup subcommands in sequence.

bash "${CLAUDE_SKILL_DIR}/scripts/setup-codex.sh"
bash "${CLAUDE_SKILL_DIR}/scripts/setup-opencode.sh"

Cleanup

Periodic maintenance tasks:

Related Skills

• harness-plan — Create project plans after setup
• harness-work — Execute tasks after setup
• harness-review — Review setup configuration