maruda

AI with a harness.

日本語版は README.ja.md にあります。

maruda is a collection of Claude Code agent skills plus a full project harness for AI-assisted development — code quality reviews, security audits, living documentation, GitHub-issue-driven implementation with autonomous verification, and day-one CI/security gates (gitleaks, Semgrep, Trivy). Built on harness engineering and loop engineering principles: the environment enforces quality mechanically (hooks, strict CI, branch protection) while a bounded improvement loop (diagnose → issue → plan → resolve ⇄ verify) does the work.

The name is marutto (まるっと, "the whole lot") plus DA — Dev with AI: the
skills, the rules, the CI and the security gates arrive together, not one at a
time.

Renamed from dev-skills. This repository moved from ymd38/dev-skills to
northraystudio/maruda on 2026-09-20. GitHub redirects the old URLs, so
one-liners and clones that still point at the old address keep working and
projects already installed need no action. New links should use the new address.

What are Skills?

Skills are Markdown files that give AI agents specialized knowledge, workflows, and output templates for specific tasks. When installed, Claude Code recognizes relevant requests and applies the skill automatically — no manual prompting required.

Continuous Improvement Cycle

These skills form a continuous improvement loop for your codebase:

graph LR
    Diagnose["🔍 Diagnose<br/>software-evaluation<br/>vulnerability-scan<br/>data-validation"]
    Visualize["📊 Visualize<br/>progress-dashboard"]
    Register["📋 Register Issues<br/>report-to-issues"]
    Draft["✍️ Draft Issue<br/>gh-issue-drafter"]
    Plan["🧠 Plan<br/>gh-issue-planner"]
    Resolve["🛠️ Resolve + Verify<br/>gh-issue-resolver"]
    Batch["📦 Batch Run<br/>gh-batch-runner"]

    Idea["💡 Rough idea<br/>(hand-written)"] -- "Loose 'what I want'" --> Draft
    Diagnose -- "Reports + JSON" --> Visualize
    Diagnose -- "Reports" --> Register
    Register -- "GitHub Issues" --> Plan
    Draft -- "Scoped GitHub Issue" --> Plan
    Plan -- "Agreed plan comment" --> Resolve
    Plan -- "Several Issues, one release" --> Batch
    Batch -- "One commit per Issue" --> Resolve
    Batch -- "One PR from epic/**" --> Done
    Resolve -- "Re-run diagnosis on the diff" --> Diagnose
    Diagnose -- "Regressions only" --> Resolve
    Resolve -- "PR + Code Changes" --> Done["✅ Verified PR"]
    Visualize -. "Track trends" .-> Done

The Resolve ⇄ Diagnose arrows are the autonomous verification loop: gh-issue-resolver
re-runs the diagnosis on its own diff, fixes the findings it caused, and re-checks — up to
3 iterations, never outside the agreed plan's impact scope. Findings that predate the change
are handed to report-to-issues instead of being fixed in the same PR.

When several Issues ship together, gh-batch-runner collects them under an Epic Issue,
lands one commit per Issue on a shared epic/** branch, verifies that branch as a whole
against the integration branch, and opens a single PR. Issues that ship separately stay on
the individual path, and a dependency chain that ships separately uses stacked PRs.

Note: spec-doc is independent of this cycle — use it anytime to generate or sync living documentation. setup is also independent: it installs the harness that makes this cycle the default path in a new project.

Available Skills

Installation

Setup by use case

Pick the row that matches your situation — each command is complete as written:

# Full one-liner (languages are explicit, never detected)
curl -fsSL https://raw.githubusercontent.com/northraystudio/maruda/main/harness/scripts/install.sh \
  | bash -s -- --langs go,typescript --pm pnpm --with-skills

# Minimal one-liner (rails only)
curl -fsSL https://raw.githubusercontent.com/northraystudio/maruda/main/harness/scripts/install.sh \
  | bash -s -- --minimal

Full harness (recommended for new projects)

Skills alone give workflows (L1). The full harness adds mechanical guardrails —
format-on-write and dangerous-command hooks, a lean CLAUDE.md, cycle rules,
GitHub Actions CI, and a security scan — so quality is maintained from day one
and the continuous improvement cycle is the default path (L2–L3).

With --langs, the installer also generates:

• .github/workflows/ci.yml — per-language jobs (Go: go.mod guard / tidy-check / build / test -race / cached pinned golangci-lint; Node: script preflight / frozen-lockfile install / lint / typecheck (TS) / test; Python: ruff / pytest). Strict by design: a missing lint/typecheck/test script — or zero tests — fails the job with an actionable ::error telling you exactly what to add, so verification lands with the first code PR
• docs/harness-checklist.md — the manual steps that turn strict CI green (add scripts, first test, commit lockfile, branch protection, promote trivy); delete it when done
• .github/workflows/security-scan.yml — gitleaks + semgrep gating from day one (shift-left), trivy staged as continue-on-error, Node production-dependency audit. Both workflows also run on direct pushes to the default branch
• .gitleaks.toml and .semgrepignore with a smallest-unit-only allowlist policy
• With --pr-agent: .github/workflows/pr-agent.yml and .pr_agent.toml — advisory AI review via qodo-ai/pr-agent (describe / review / improve when a PR opens, /review on each push, slash commands for repository members; action pinned to a release-tag SHA). Opt-in because it needs an OPENAI_KEY secret and API billing; never a required check, and it composes with --no-ci for projects that already have CI
• .env.example and .gitignore entries for .env
• .claude/rules/ — the cycle contract, score-aligned coding principles (KISS / YAGNI plus the five evaluation pillars inverted into "write it right the first time" rules), and per-language best practices (go.md / python.md / typescript.md, installed per --langs). Each rule is tagged with the software-evaluation pillar it scores on; the security rules preempt vulnerability-scan findings

Disable with --no-ci; skip individual components with --no-format-hook /
--no-bash-guard / --no-guidance-hooks / --no-rules / --no-env-guard;
add the advisory PR Agent with --pr-agent.
CI tool and action versions are pinned (no @latest); the local format hook
only runs project-installed formatters and never downloads code.

Checks gate merges only when branch protection marks them required. The
installer reports the protection state in its checklist; pass --protect
(needs gh auth with admin on a pushed default branch) to apply required
status checks automatically, or configure them in GitHub settings.

Gate maturity ladder

The defaults are day-one settings. Promote gates as the project matures:

PR Agent (--pr-agent) sits outside the ladder on purpose: it is advice, not
a gate, and --protect never adds it to the required checks.

Installer regression tests: bash harness/tests/run.sh.

# From a clone (one-liners: see "Setup by use case" above)
./harness/scripts/setup.sh --target /path/to/your-project --langs python --python-pm uv

Prefer inspecting scripts before piping to bash:

curl -fsSL https://raw.githubusercontent.com/northraystudio/maruda/main/harness/scripts/install.sh -o install.sh
less install.sh && bash install.sh --langs go

Existing files are never overwritten. When an incoming file differs from
what you already have, it is written alongside as <file>.new (pacman
.pacnew style) — review with diff <file> <file>.new, merge what you want,
then delete the .new. Identical files clear stale .new proposals;
--force overwrites outright. settings.json is the exception: its hooks
are merged automatically (existing entries preserved). The final checklist
lists every proposed file.
Supported languages: Go, Python, TypeScript, JavaScript. Run setup.sh --help for all flags.

Migrating from the yds- names: the yds- prefix is gone. It existed to
group the skills in a flat command list, and the plugin namespace now does that
job — /yds-spec-doc becomes /maruda:spec-doc under the plugin, or /spec-doc
via npx skills add. In projects installed before the rename, delete the old
.claude/skills/yds-* directories and reinstall; leaving them registers every
skill twice. The cycle rule moved with it: .claude/rules/dev-skills-cycle.md is
replaced by .claude/rules/maruda-cycle.md, and setup.sh reports the stale file
rather than deleting something it did not write. The submodule path in the
examples below is now .claude/maruda (git mv .claude/dev-skills .claude/maruda
if you use one). Handoff markers (<!-- gh-issue-planner:agreed-plan --> etc.)
and JSON summary type values keep the legacy names, so existing issues and
dashboard data remain compatible.

Skills only

Option 1: Claude Code plugin (Recommended)

/plugin marketplace add northraystudio/maruda
/plugin install maruda@northraystudio

Every skill arrives namespaced — /maruda:spec-doc, /maruda:setup,
/maruda:gh-issue-planner — so nothing collides with other skill collections,
and the bundled harness/scripts/setup.sh is always the same version as the
skills. /maruda:setup then installs the harness itself; the plugin cannot write
files into your project, so CLAUDE.md, hooks, settings.json, rules and CI stay
setup.sh's job.

To pin a release instead of tracking main, add the marketplace with a ref:

// .claude/settings.json
{
  "extraKnownMarketplaces": {
    "northraystudio": {
      "source": { "source": "github", "repo": "northraystudio/maruda", "ref": "v0.1.0" }
    }
  },
  "enabledPlugins": { "maruda@northraystudio": true }
}

setup.sh --plugin writes exactly those two keys for you (--plugin-ref v0.1.0
to pin a tag), merging into whatever is already in settings.json. Note that
Claude Code does not auto-install from settings: the keys make the marketplace
known and mark the plugin enabled, and each person still runs
/plugin install maruda@northraystudio once.

Option 2: CLI Install (any agent)

# All skills, non-interactive, copied into .claude/skills/
npx skills add northraystudio/maruda --skill '*' --agent claude-code -y --copy

Running plain npx skills add northraystudio/maruda opens an interactive picker
where nothing is pre-selected — press Space to select skills before Enter,
or use the flags above. --copy copies files instead of symlinking, so the
skills can be committed and shared with your team.

To install a single skill:

npx skills add northraystudio/maruda --skill spec-doc --agent claude-code -y --copy

Option 3: Manual Copy

Copy any skill directory into your project:

cp -r skills/spec-doc .claude/skills/spec-doc

Or copy all skills at once:

cp -r skills/* .claude/skills/

Option 4: Git Submodule

Add as a submodule to keep skills up to date with upstream changes:

git submodule add https://github.com/northraystudio/maruda.git .claude/maruda

Then reference skills from .claude/maruda/skills/.

Usage

Once installed, describe your task naturally and the relevant skill is applied automatically:

"Generate a spec for src/api/"
→ Uses spec-doc skill

"Review the code quality of src/backend/"
→ Uses software-evaluation skill

"Scan src/ for security vulnerabilities"
→ Uses vulnerability-scan skill

"Check the data quality of db/" / "データ検証して" / "NULL率を調べて"
→ Uses data-validation skill

"Create GitHub Issues from docs/evaluation/myapp.20260406.md"
→ Uses report-to-issues skill

"Turn this into an issue" / "ざっくり書くのでIssueにして"
→ Uses gh-issue-drafter skill

"Plan issue #42" / "Issue #42の対応方針を立てて"
→ Uses gh-issue-planner skill

"Implement issue #42" / "Issue #42を実装して"
→ Uses gh-issue-resolver skill (requires an agreed plan comment from gh-issue-planner)

"Issue 1,2,3をまとめて対応して" / "Ship these issues as one release"
→ Uses gh-batch-runner skill (requires an agreed plan comment on every member Issue)

"Generate a progress dashboard" / "Show improvement trends"
→ Uses progress-dashboard skill

"Set up the harness" / "セットアップして" / "ハーネスを入れて"
→ Uses setup skill (interview-style, writes only after approval)

You can also invoke skills directly:

/maruda:spec-doc src/
/maruda:software-evaluation src/backend/
/maruda:vulnerability-scan src/
/maruda:data-validation db/
/maruda:report-to-issues docs/evaluation/myapp.20260406.md
/maruda:gh-issue-drafter
/maruda:gh-issue-planner
/maruda:gh-issue-resolver
/maruda:gh-batch-runner
/maruda:progress-dashboard
/maruda:setup

Skill Categories

Documentation

• spec-doc — Generates a machine-readable "Living Specification" (docs/spec.md) from source code. Covers architecture, interfaces, data models, state transitions, and development constraints. Syncs with existing specs rather than replacing them.

Code Quality

• software-evaluation — Scores a codebase across five pillars with evidence-based findings (file:line citations required). Produces a prioritized roadmap with P0–P3 action items.

Security

• vulnerability-scan — Combines automated Semgrep scanning with a manual review checklist covering OWASP Top 10. Triages true positives from false positives and includes a dependency CVE audit.

Data

• data-validation — Checks record counts, NULL rates (including empty strings, zero values, and sentinels), value distribution, uniqueness, referential integrity, and format validity. Reads only from the project's own fixtures/seeds or an explicitly configured non-production connection — never a guessed or production source. Every finding carries up to 5 sampled rows with PII masked, and every expectation is traced back to a schema constraint, type definition, or test assertion. Classifies each finding as regression / pre-existing / environmental so gh-issue-resolver knows what it is allowed to fix. Writes no JSON and, by default, no file at all — routine validation should not grow the commit target.

Visualization

• progress-dashboard — Reads JSON summaries from software-evaluation and vulnerability-scan, then generates a self-contained HTML dashboard with quality score trends, radar charts, security findings trends, roadmap progress, and dependency risk panels.

Issue Management

• report-to-issues — Decomposes evaluation or security-audit reports into actionable tasks, presents them for user selection, and registers the chosen items as GitHub Issues with appropriate labels and priority.

• gh-issue-drafter — Takes a loose, hand-written "what I want" and drafts the structure it almost always lacks (machine-checkable 完了条件, 触らない範囲, optional 設計方針). After author approval, files the Issue tagged with <!-- gh-issue-drafter:scoped-issue --> so gh-issue-planner treats the scope as binding. The human-authored counterpart to report-to-issues.

• gh-issue-planner — Fetches a GitHub Issue via gh CLI, classifies it (bug/feature/refactor/docs), searches related code, and presents a structured plan (approach, impact scope, steps, open questions). Posts the agreed plan as an issue comment tagged with <!-- gh-issue-planner:agreed-plan -->.

• gh-issue-resolver — Picks up the agreed plan comment posted by gh-issue-planner, creates a feature branch, applies the changes, runs tests, opens a Pull Request, and verifies the fix against the original issue. Verification is autonomous: it re-runs whichever diagnoses the diff triggers, attributes each finding against the base branch, and fixes the regression-class findings itself — bounded to 3 iterations and to the agreed plan's impact scope, returning to gh-issue-planner when it hits either wall. pre-existing findings are never fixed in the same PR; they are offered to report-to-issues.

• gh-batch-runner — Runs several planned Issues as one release. Membership is an Epic Issue holding the members as sub-issues (gh api .../sub_issues), and ordering comes from GitHub's blocked_by dependencies, both re-read at the start of every run. Each Issue lands as a single commit on epic/<n>-<slug> under the usual per-Issue limits; no child PRs are created. The branch is then verified as a whole against the integration branch — what newly breaks there is the batch's regression and is fixed, what already failed is handed to report-to-issues — and a single Pull Request opens into the integration branch, where CI and review actually gate.

Setup

• setup — Installs the full harness into the current project through a short interview: a lean CLAUDE.md (Stack & commands, cycle, hard rules), four hooks (format-on-write, dangerous-bash guard, SessionStart context, Stop nudge), a merged .claude/settings.json, and .claude/rules/maruda-cycle.md. Languages (Go / Python / TypeScript / JavaScript) are asked, never auto-detected; nothing is written before the confirmation summary is approved. The non-interactive counterparts are harness/scripts/install.sh (one-liner) and harness/scripts/setup.sh.

Progress Dashboard Preview

Sample dashboard generated from 3 months of evaluation and security scan data. Open examples/progress-dashboard/dashboard.html in a browser to try it interactively.

Examples

The examples/progress-dashboard/ directory contains working sample data:

License

MIT