e228faabf5
G-1: 메신저 Webhook Relay + _send_to_room 실제 httpx 호출 구현 G-2: POST /api/tasks/bulk SR 대량작업 엔드포인트 (최대 100건) G-3: 라이선스 만료 알림 스케줄러 (매일 09:00 KST) G-4: 체험판 upgrade_banner 필드 + license.py 배너 로직 G-5: core/auto_rca.py + incidents/problem auto-rca 엔드포인트 G-6: core/deploy_impact.py + vibe impact-analysis 엔드포인트 G-7: core/ticket_classifier.py + SR 생성 시 AI 분류 + ai-suggestion API G-8: VulnPatchRecord 모델 + vuln_scan 패치추적 4개 엔드포인트 G-9: core/jira_sync.py + gateway Jira/Confluence 연동 엔드포인트 G-10: core/push_notify.py + routers/push.py + PushSubscription 모델 G-11: approvals 다중승인 (위임/서명/기한초과/마감연장) G-12: alembic.ini + migrations/ + cicd/migrate_to_postgres.sh 하네스: guardia-orchestrator 확장기능 Phase 반영 봇명령어: /sr /status /license /bulk 슬래시 명령어 추가 설치스크립트: setup/ (Ubuntu, CentOS, RHEL, Windows) --test 옵션 포함 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
212 lines
8.0 KiB
Markdown
212 lines
8.0 KiB
Markdown
# Contributing to Harness
|
||
|
||
Thanks for considering a contribution to **Harness** — a Claude Code meta-skill factory that designs agent teams and generates skills.
|
||
|
||
This document covers: response SLAs, how to contribute, development setup, PR conventions, commit message rules, code of conduct, and maintainer list.
|
||
|
||
---
|
||
|
||
## Response SLA (commitments)
|
||
|
||
These are the maintainer response targets for this repository. They are **conservative** so that a small maintainer team can realistically keep them while scaling.
|
||
|
||
| Surface | Target | Notes |
|
||
|---------|--------|-------|
|
||
| PR — 1st response | **< 72h** | Business days. A "1st response" means at minimum a label + one comment acknowledging the PR. |
|
||
| Issue triage & labeling | **< 48h** | Every new issue gets `needs-triage` removed and a type label (`bug` / `enhancement` / `question` / `discussion`) within 48h. |
|
||
| Bug resolve (P0 / P1) | **< 14d** | P0 = data loss / security / broken install. P1 = common path broken. P2/P3 tracked on roadmap without a hard SLA. |
|
||
| Security report | **< 7d** | Initial acknowledgement within 7 days. Patch target 30 days. Please see **Security** section below for the private channel. |
|
||
| Release cadence | **every 2 weeks** | Biweekly tag unless there is nothing shippable. P0 fixes may cut an off-schedule patch release. |
|
||
|
||
If we miss an SLA, please feel free to ping the issue/PR — that is not rude, it is the agreed feedback loop.
|
||
|
||
---
|
||
|
||
## How to Contribute
|
||
|
||
Different kinds of contributions go through different entry points. Pick the one that fits.
|
||
|
||
### Bug report
|
||
|
||
- Open an issue using the **Bug report** form (`.github/ISSUE_TEMPLATE/bug_report.yml`).
|
||
- Required: Claude Code version, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag state, reproduction steps, expected vs actual, OS.
|
||
- Small reproductions (< 30 lines) are ideal. If your repro needs a full project, link a public fork.
|
||
|
||
### Feature request
|
||
|
||
- Open an issue using the **Feature request** form.
|
||
- We expect a short "what problem does this solve" paragraph. If you have a proposal, put it in the PR-ready shape (which of the 6 team-architecture patterns does it extend / replace?).
|
||
|
||
### Question
|
||
|
||
- Open an issue using the **Question** form, **or** start a thread in [GitHub Discussions](https://github.com/revfactory/harness/discussions) if the matter is open-ended.
|
||
|
||
### Discussion (RFC-sized ideas)
|
||
|
||
- Prefer GitHub Discussions. Only promote to an issue once there is rough consensus on direction.
|
||
|
||
### Pull Request
|
||
|
||
- See **Pull Request Guidelines** below.
|
||
- Small PRs merge faster. Anything > 400 lines of diff should probably have been a Discussion first.
|
||
|
||
### Security
|
||
|
||
- Do **not** open a public issue for anything that could be abused.
|
||
- Email: `robin.hwang@kakaocorp.com` with subject prefix `[harness-security]`.
|
||
- We aim to acknowledge within 7 days (see SLA table).
|
||
|
||
---
|
||
|
||
## Development Setup
|
||
|
||
### Prerequisites
|
||
|
||
- Claude Code `v2.x` (Agent Teams API required)
|
||
- Node.js `>= 18` (for local tooling used in CI)
|
||
- Git
|
||
|
||
### Environment flag
|
||
|
||
Harness currently requires Claude Code's experimental Agent Teams feature. Set the flag in your shell profile or per-session:
|
||
|
||
```bash
|
||
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
|
||
```
|
||
|
||
We track this dependency in `docs/experimental-dependency.md` (if Anthropic promotes the flag to stable, we update the README within 72h per the SLA above).
|
||
|
||
### Local plugin link
|
||
|
||
To test your changes in a local Claude Code session without publishing to the marketplace:
|
||
|
||
```bash
|
||
# From your checkout
|
||
claude plugin link ./harness
|
||
|
||
# Verify
|
||
claude plugin list | grep harness
|
||
```
|
||
|
||
Unlink with `claude plugin unlink harness` when you're done.
|
||
|
||
### Running the meta-skill
|
||
|
||
```bash
|
||
claude "build a harness for a fintech risk-assessment team"
|
||
```
|
||
|
||
Scaffolded agents and skills land under `.claude/agents/` and `.claude/skills/` in the target project.
|
||
|
||
### Tests & lints
|
||
|
||
- Markdown lint: `npx markdownlint '**/*.md'`
|
||
- YAML lint (issue templates & workflows): `npx yaml-lint .github/`
|
||
- Skill metadata validation: `python scripts/validate_skills.py` (if present)
|
||
|
||
CI runs these on every PR. Local execution is encouraged but not required — we won't block on CI-caught issues that are trivial to fix on merge.
|
||
|
||
---
|
||
|
||
## Pull Request Guidelines
|
||
|
||
### Branch naming
|
||
|
||
Use the `type/short-description` shape:
|
||
|
||
| Prefix | Use for | Example |
|
||
|--------|---------|---------|
|
||
| `feat/` | New user-visible capability | `feat/expert-pool-variance-mode` |
|
||
| `fix/` | Bug fix | `fix/agent-teams-flag-detection` |
|
||
| `docs/` | Docs-only changes | `docs/quickstart-gemini-section` |
|
||
| `refactor/` | Internal structure, no behavior change | `refactor/skill-loader-split` |
|
||
| `chore/` | Build, deps, housekeeping | `chore/upgrade-markdownlint` |
|
||
| `test/` | Tests only | `test/fan-out-fan-in-e2e` |
|
||
|
||
### Commit message language
|
||
|
||
- **Korean and English are both accepted.** Write in whichever you are more precise in.
|
||
- If the change will appear in the CHANGELOG or release notes, please also provide an English title in the PR description so downstream readers can follow.
|
||
|
||
### PR template
|
||
|
||
Every PR body is pre-filled from `.github/PULL_REQUEST_TEMPLATE.md`. Please fill in:
|
||
|
||
- **Summary** (what & why, 2–4 sentences)
|
||
- **Motivation** (link issue, reference research, or 1-line rationale)
|
||
- **Scope of change** (checklist of touched surfaces)
|
||
- **Tests** (what you ran / added)
|
||
- **CHANGELOG** (did you update `CHANGELOG.md`? Y/N/NA)
|
||
- **SemVer impact** (patch / minor / major — see next section)
|
||
|
||
### Review expectation
|
||
|
||
- One approving review from a maintainer is required.
|
||
- We try to respond on PRs within 72h (see SLA). If you're blocked, ping.
|
||
|
||
---
|
||
|
||
## Commit Message Convention
|
||
|
||
We follow a light variant of **Conventional Commits** that maps directly to SemVer.
|
||
|
||
```
|
||
<type>(<scope>)!: <short summary>
|
||
|
||
<body — optional>
|
||
|
||
<footer — optional>
|
||
```
|
||
|
||
### Types & SemVer mapping
|
||
|
||
| Commit type | SemVer impact | Example |
|
||
|-------------|---------------|---------|
|
||
| `feat!:` or `BREAKING CHANGE:` in footer | **major** (e.g. 1.x → 2.0) | `feat!: rename primary pattern "Supervisor" → "Orchestrator"` |
|
||
| `feat:` | **minor** (e.g. 1.2 → 1.3) | `feat: add Producer-Reviewer variance metric` |
|
||
| `fix:` | **patch** (e.g. 1.2.3 → 1.2.4) | `fix: correct flag detection on zsh` |
|
||
| `docs:` / `chore:` / `refactor:` / `test:` | no release bump | `docs: clarify Gemini roadmap` |
|
||
|
||
- Korean summaries are fine: `feat: 전문가 풀 패턴에 분산 지표 추가`.
|
||
- The `!` suffix (or `BREAKING CHANGE:` footer) is the **only** canonical major-version trigger. Please do not set it lightly.
|
||
|
||
### Release tagging
|
||
|
||
- Releases are cut every 2 weeks (see SLA).
|
||
- Tagging happens from `main` after CI passes and CHANGELOG is updated.
|
||
- Tags follow `vMAJOR.MINOR.PATCH` (e.g. `v1.3.0`).
|
||
|
||
---
|
||
|
||
## Code of Conduct
|
||
|
||
This project adheres to the **Contributor Covenant v1.4** — in short:
|
||
|
||
- Be welcoming and inclusive. Assume good intent.
|
||
- No harassment, no personal attacks, no discriminatory language.
|
||
- Critique ideas, not people. Back claims with references where possible.
|
||
- Maintainers may moderate, edit, or remove comments/commits/issues/PRs that violate these principles, and may ban offenders.
|
||
|
||
Full text: <https://www.contributor-covenant.org/version/1/4/code-of-conduct/>
|
||
|
||
Report Code of Conduct violations privately to `robin.hwang@kakaocorp.com` with subject prefix `[harness-coc]`.
|
||
|
||
---
|
||
|
||
## Maintainers
|
||
|
||
| Role | Handle | Area |
|
||
|------|--------|------|
|
||
| Lead maintainer | [@revfactory](https://github.com/revfactory) | Project direction, releases, final review |
|
||
| Contributor | [@hnts03](https://github.com/hnts03) | Skill templates, Korean documentation |
|
||
| Contributor | [@JunghwanNA](https://github.com/JunghwanNA) | Agent patterns, integration tests |
|
||
| Contributor | [@shaun0927](https://github.com/shaun0927) | Tooling, CI, infra |
|
||
|
||
New contributors become listed here after sustained contribution (not a single PR). Drop a note in a Discussion if you'd like to discuss a maintainer path.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
By contributing, you agree that your contributions will be licensed under the same license as this repository (see [`LICENSE`](./LICENSE)).
|