maruda Full Harness Setup (Interview Mode)

Goal

Turn the current repository into a project that runs the Diagnose → Register/Draft → Plan → Resolve ⇄ Verify cycle with mechanical guardrails (hooks) and a lean CLAUDE.md.

Skills alone are L1. This setup adds L2–L3: a short project brain (CLAUDE.md), hard rails (hooks + settings), and cycle guidance (rules). It never creates scheduled or cron-driven automation (L4); event-driven GitHub Actions — strict CI and the opt-in PR Agent review — are L2–L3 and in scope.

Principles

• Interview, no auto-detection. Do NOT infer languages from go.mod, package.json, etc., even when they exist. This setup targets pre-development projects where detection misleads. File existence is used only for overwrite/merge prompts.
• Never overwrite existing CLAUDE.md / settings / hooks without explicit per-file approval. Prefer merge (append missing sections).
• Hooks enforce hard rules; CLAUDE.md holds soft guidance. Keep CLAUDE.md short — detail lives in skills and .claude/rules/.
• Write files only after the user approves the Phase 4 summary.

Workflow

Ask one phase at a time and wait for answers. If the user says "use defaults", still require the primary language choice, then apply the defaults table below to everything else.

How to ask (question-tool contract)

When a structured question tool (e.g. AskUserQuestion) is available, use one call per phase, and keep every call within the tool's contract — violating it aborts the turn with "Invalid tool parameters":

• At most 4 questions per call; every question needs 2–4 predefined options — never an empty or single-option list. A free-text "Other" choice is provided by the tool automatically; rely on it for custom values instead of inventing an "enter manually" option list.
• Free-form items (project name, custom commands) must still offer 2+ options: make option 1 the recommended default (e.g. "Use directory name:<dir> (Recommended)") and a sensible alternative; custom values arrive via the built-in Other.
• Multi-choice items (additional languages, components) use the tool's multi-select mode.
• If the tool is unavailable or returns an error, fall back to asking the same questions as plain chat text and wait for the answers — never skip a phase because the tool failed.

Phase 0 — Preconditions

1. Confirm the target is a git repository (offer git init if not).
2. Check existence (existence only — do not read to guess the stack) of: CLAUDE.md, .claude/settings.json, .claude/hooks/, .claude/rules/maruda-cycle.md, .claude/skills/.
3. Tell the user: existing files will each get an overwrite/merge/skip question in Phase 3.

Phase 1 — Project skeleton (required)

• Q1. Project name — options: "Use directory name: <dir> (Recommended)" / "Use repository name" (custom names come via Other).
• Q2. Primary language (choose exactly one): Go / Python / TypeScript / JavaScript.
• Q3. Additional languages (multi-select) — none, or any others from the same list.
• Q4. Default branch — options: main (Recommended) / master (anything else via Other).

Phase 1b — Flow (second call; Phase 1 is already at the 4-question limit)

• Q5. Integration branch — the branch PRs target and CI gates. Options: "Same as the default branch: <branch> (Recommended)" / staging (anything else via Other). It is recorded in CLAUDE.md, not detected.
• Q6. Default flow when several Issues run at once — options: individual (Recommended — one PR per Issue) / batch (collect them on epic/<n>-<slug>, verify as a whole, one PR) / stack (each PR targets the branch of the Issue it depends on). This is only the default: whether Issues are batched is decided by asking "do these ship together?", never by the dependency graph.

Phase 2 — Per-language commands

Ask for the primary language in full; for additional languages a quick confirm of the defaults is enough. Propose these defaults:

• Node projects: ask the package manager first (pnpm / npm / yarn / bun; propose pnpm), then substitute {pm}.
• TypeScript only: also ask about typecheck ({pm} exec tsc --noEmit / a script name / none).
• Python only: ask the package manager (uv / pip / poetry; propose uv). If uv, ask: "Enable a hook that blocks pip install in favor of uv add?" (Y/n).

Phase 3 — Harness scope

• Q-H1. Components (multi-select, every entry recommended ON by default): CLAUDE.md / format hook / bash-guard hook / SessionStart + Stop guidance hooks / .claude/rules/ (cycle contract + score-aligned coding principles + per-language rules for the chosen languages) / GitHub Actions CI (ci.yml per language + security-scan.yml + .gitleaks.toml + .semgrepignore; gitleaks and semgrep are hard gates from day one — shift-left — while trivy starts as informational continue-on-error) / .env guard (.gitignore entries + .env.example).
• Q-H1b. Optional paid add-on (default OFF; independent of the CI answer — it composes with a project's existing CI): PR Agent (.github/workflows/pr-agent.yml + .pr_agent.toml; advisory qodo-ai/pr-agent review — describe / review / improve when a PR opens, /review on each push, slash commands for repository members). Needs an OPENAI_KEY repository secret and API billing; it is advice, never a required status check.

• Q-H1c. How the skills get installed (single choice, propose plugin):

  • plugin — the Claude Code plugin. Commands are namespaced (/maruda:spec-doc), and the skills always match the setup.sh that installed the harness. Maps to --plugin (add --plugin-ref <tag> when the user wants a pinned release rather than main). Say plainly that Claude Code does not auto-install from settings: --plugin records the marketplace and marks the plugin enabled, and each person still runs /plugin install maruda@northraystudio once.
  • npx — npx skills add northraystudio/maruda --skill '*' --agent claude-code -y --copy. Works with agents other than Claude Code; commands have no namespace (/spec-doc), so they can collide with other skill collections. Maps to --with-skills.
  • neither — the user installs skills themselves. No flag.

  --plugin and --with-skills are two ways to install the same skills, so the installer rejects them together. If the project already has .claude/skills/yds-* from an older install, say that those directories are now stale and should be deleted — the plugin ships the same skills under their new names, and leaving both registers each skill twice.

• Q-H2. Per existing file: merge (append only the missing sections) / back up then replace / skip.
• Q-H3. Bash guard strength: standard (rm -rf /, force-push to the default branch, redirects into .env) / standard + pip guard (uv projects) / none.

Phase 4 — Confirm, then apply

Show a summary of every answer and every file that will be created or modified. Wait for explicit approval. On approval, apply as follows.

Preferred path — run the installer, then refine:

1. Locate harness/scripts/setup.sh, in this order — the first hit wins:

   • this skill's own plugin copy, "${CLAUDE_PLUGIN_ROOT}/harness/scripts/setup.sh". When maruda runs as a plugin, CLAUDE_PLUGIN_ROOT is set in the shell, the whole repository is in the plugin cache, and the script keeps its executable bit. Prefer it: the installer is then guaranteed to be the same version as the skills running the interview. Check with [[ -n "${CLAUDE_PLUGIN_ROOT:-}" && -f "${CLAUDE_PLUGIN_ROOT}/harness/scripts/setup.sh" ]].
   • the working repository, if it is maruda or contains a clone/submodule (harness/scripts/setup.sh, .claude/maruda/harness/scripts/setup.sh).

   • the network, via the official one-liner. Pin a release tag rather than main so the installer matches a known version (network required):

     curl -fsSL https://raw.githubusercontent.com/northraystudio/maruda/main/harness/scripts/install.sh \
       | bash -s -- --langs <langs> --pm <pm> --python-pm <py-pm> --branch <branch> --name <name> \
         [--integration-branch <branch>] [--default-flow <individual|batch|stack>] \
         [--guard-pip] [--with-skills] [--pr-agent]

   Map EVERY Phase 1b / Phase 3 answer to a flag — the applied changes must equal the approved summary exactly: languages (primary first) → --langs, Node PM → --pm, Python PM → --python-pm, pip guard → --guard-pip, integration branch → --integration-branch (omit when it equals the default branch), default flow → --default-flow, skill install method → --plugin (+ --plugin-ref) or --with-skills or neither, CI OFF → --no-ci, format hook OFF → --no-format-hook, bash guard OFF → --no-bash-guard, guidance hooks OFF → --no-guidance-hooks, rules OFF → --no-rules, .env guard OFF → --no-env-guard, PR Agent ON → --pr-agent (allowed with --no-ci, never with --minimal). If the user wants branch protection applied and gh is authenticated with admin rights, add --protect. The installer never overwrites existing files, which is exactly the merge-safe behavior wanted here.

2. Then reconcile whatever the installer reported as "kept existing" or "proposed" against the user's Phase 3 answers:
   • The installer never overwrites: files that differ from the incoming version are written as <file>.new. For each one, show the user the diff and offer to merge it (or discard the .new) — apply only what they approve, then delete the .new file.
   • CLAUDE.md kept + user chose merge → append only the missing sections (Stack & commands for the chosen languages, the cycle section, Hard rules), following harness/templates/CLAUDE.md.template.
   • settings kept unmerged (no jq) → merge the hooks block by hand, preserving every existing user hook.
   • Any file the user chose to skip → leave untouched even if the installer would have created it (delete nothing; just don't add).
3. Adjust generated CLAUDE.md commands to any non-default answers from Phase 2 (e.g. a custom test script name).

Fallback (no network, no local copy): report that the harness templates are unavailable and stop after writing only what can be written faithfully from this document — do not improvise hook scripts from memory.

Phase 5 — Verify and report

Print a final checklist:

[maruda harness]
  skills:     OK (N) / MISSING
  CLAUDE.md:  CREATED / MERGED / SKIPPED
  hooks:      OK (selected scripts, executable)
  settings:   OK / MERGED / needs manual merge
  rules:      OK / skipped
  CI:         OK / skipped
  flow:       integration branch: <branch> | default: <individual|batch|stack>
  protection: configured / NOT CONFIGURED / applied
  pr-agent:   disabled / written (OPENAI_KEY secret required)
  next:       restart Claude Code to load hooks, then try /maruda:software-evaluation .

Two follow-ups matter for the gates to actually gate:

• Branch protection. A CI check only blocks merges once it is a required status check. The installer reports the state; if it says NOT CONFIGURED, treat setup as incomplete and either re-run with --protect (needs gh auth + admin + a pushed default branch) or walk the user through GitHub settings. Do not report overall success while protection is unconfigured — report it as an explicit remaining step.
• Strict CI. The generated jobs intentionally fail when lint / typecheck / test scripts (or any tests) are missing. Tell the user the first code PR must land with those in place — that is the shift-left contract, not a bug.
• PR Agent secret. If --pr-agent was applied, the PR Agent workflow fails on every PR until the OPENAI_KEY repository secret exists. Report it as an explicit remaining step; it is advisory and must never be added to required status checks.

Remind the user that hooks load at session start — a restart (or new session) is needed before the guard/format hooks take effect.

Stop conditions

• User declines the Phase 4 summary → stop after reporting what would have changed. Write nothing.
• User declines an overwrite → keep the file, note it in the checklist.
• Unknown/other language requested → set up the supported languages, leave a # TODO stack block for the rest, and say so.

Non-goals

• No scheduled loops or cron (L4) — separate task only. Event-driven GitHub Actions (CI, PR Agent) are in scope.
• No Semgrep / gh installation — mention prerequisites, don't install.
• No rewriting of existing architecture docs or unrelated refactors.