Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,25 @@ Versioning: skill bundle uses `skills-vX.Y.Z` tags; quivo CLI uses `cli-vX.Y.Z`
- Initial open-source release of **quivo** — a forkable, multi-LLM skill
distribution CLI for AI coding agents.
- CLI commands: `init`, `sync`, `update` (self-upgrade), `list`, `doctor`.
- Adapters for Claude Code (`.claude/skills/`) and Codex CLI (`.codex/`).
- Adapters for Claude Code (`.claude/skills/`) and Codex CLI
(`.agents/skills/`, per the open agent skills standard).
- `q-` namespace prefix for installed skills (directory and frontmatter
`name:`) so quivo skills never collide with a project's own skills.
Names are normalized to the validators' `^[a-z0-9-]+$` requirement.
- Frontmatter normalization on install: only validator-accepted keys
(`name`, `description`, `license`, `allowed-tools`, `metadata`) stay
top-level; all other keys (`version`, `scope`, `risk`, `outputs`, ...)
move under `metadata:` so Codex discovery doesn't reject the skill.
- Managed skill-list block in agent context files (`CLAUDE.md` for Claude
Code, `AGENTS.md` for Codex), regenerated on `init`/`sync`.
- Clean reinstall on `init`/`sync`: the previous install — every file
recorded in `.quivo-lock.json`'s per-skill manifests — is removed before
installing fresh, so layout/prefix changes never leave stale copies.
Known pre-manifest layouts (`.codex/prompts/`, `.codex/scripts/`,
unprefixed directories) are cleaned as a fallback, and skills dropped
from the skill source are uninstalled on `sync`.
- `.quivo-lock.json` records installed file paths per skill (including
internal skills), the manifest driving clean reinstalls.
- Repo resolution via `quivo.yml` (`repo:` key) → `QUIVO_REPO` env → built-in
default, so a fork declares its skill source once.
- Install-time injection: `.quivo/policy.md` (company policy) and
Expand Down
7 changes: 5 additions & 2 deletions README.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,11 @@ quivo init

`quivo init`은 현재 프로젝트에 번들 예제 스킬을 설치합니다.

- Claude Code: `.claude/skills/<name>/`
- Codex CLI: `.codex/prompts/<name>.md` + `.codex/scripts/<name>/`
- Claude Code: `.claude/skills/q-<name>/` (호출명 `/q-<name>`)
- Codex CLI: `.agents/skills/q-<name>/` (open agent skills 표준, 호출명 `$q-<name>`)

설치 시 `CLAUDE.md` / `AGENTS.md`에 스킬 목록 관리 블록을 유지하고,
구버전 quivo가 남긴 설치 경로를 자동 정리합니다.

---

Expand Down
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,11 @@ quivo init
```

`quivo init` installs the bundled example skills into the current project:
- `.claude/skills/<name>/` for Claude Code
- `.codex/prompts/<name>.md` + `.codex/scripts/<name>/` for Codex CLI
- `.claude/skills/q-<name>/` for Claude Code (invoked as `/q-<name>`)
- `.agents/skills/q-<name>/` for Codex CLI (open agent skills standard, invoked as `$q-<name>`)

It also maintains a managed skill-list block in `CLAUDE.md` / `AGENTS.md`,
and cleans up install layouts left behind by older quivo versions.

---

Expand Down
30 changes: 17 additions & 13 deletions docs/GUIDE.ko.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,8 +88,8 @@ quivo init

| 선택 | 입력값 | 설치 위치 |
|------|--------|-----------|
| `1` | `claude` | `.claude/skills/` |
| `2` | `codex` | `.codex/prompts/`, `.codex/scripts/` |
| `1` | `claude` | `.claude/skills/q-<name>/` |
| `2` | `codex` | `.agents/skills/q-<name>/` |
| `3` | `both` | Claude Code와 Codex 둘 다 |

자동화 스크립트나 문서에서 대화형 선택을 피하고 싶다면 `--agent`를 직접 지정합니다.
Expand All @@ -115,9 +115,10 @@ quivo init --agent codex
설치가 끝나면 대상 프로젝트에 다음 파일들이 생깁니다.

```text
.claude/skills/<skill-name>/SKILL.md
.codex/prompts/<skill-name>.md
.codex/scripts/<skill-name>/SKILL.md
.claude/skills/q-<skill-name>/SKILL.md
.agents/skills/q-<skill-name>/SKILL.md
CLAUDE.md # quivo 스킬 목록 관리 블록
AGENTS.md # quivo 스킬 목록 관리 블록
.quivo-lock.json
```

Expand Down Expand Up @@ -146,13 +147,18 @@ quivo list --dir /path/to/your/project
quivo sync
```

모든 sync는 **클린 재설치**입니다: 이전 설치본(`.quivo-lock.json`에 기록된
모든 파일)을 먼저 제거한 뒤 현재 레이아웃으로 새로 설치합니다. 레이아웃이
바뀌어도 구버전 파일이 쌓이지 않고, 스킬 소스에서 제거된 스킬은 함께
언인스톨됩니다.

특정 프로젝트를 지정하려면 다음처럼 실행합니다.

```bash
quivo sync --dir /path/to/your/project
```

이미 파일이 있고 quivo가 덮어쓰기를 거부하면, 내용을 확인한 뒤 필요할 때만
quivo가 직접 쓰지 않은 파일과 충돌하면 내용을 확인한 뒤 필요할 때만
`--force`를 붙입니다.

```bash
Expand Down Expand Up @@ -374,9 +380,8 @@ QUIVO_LOCAL_SKILLS="$PWD" quivo init --agent both --dir "$TMPPROJECT" --no-polic
quivo list --dir "$TMPPROJECT"
```

새 스킬이 Claude Code 쪽 `.claude/skills/<skill-name>/`와 Codex 쪽
`.codex/prompts/<skill-name>.md`, `.codex/scripts/<skill-name>/`에 생기면 설치 경로가
정상입니다.
새 스킬이 Claude Code 쪽 `.claude/skills/q-<skill-name>/`와 Codex 쪽
`.agents/skills/q-<skill-name>/`에 생기면 설치 경로가 정상입니다.

## 로컬 체크아웃에서 바로 설치하기

Expand Down Expand Up @@ -505,9 +510,8 @@ All skills are up to date.
마지막으로 실제 파일이 만들어졌는지 확인합니다.

```bash
test -f "$SMOKEDIR/.claude/skills/author-skill/SKILL.md"
test -f "$SMOKEDIR/.codex/prompts/author-skill.md"
test -f "$SMOKEDIR/.codex/scripts/author-skill/SKILL.md"
test -f "$SMOKEDIR/.claude/skills/q-author-skill/SKILL.md"
test -f "$SMOKEDIR/.agents/skills/q-author-skill/SKILL.md"
echo "smoke files ok"
```

Expand Down Expand Up @@ -545,7 +549,7 @@ rm -rf "$VENVDIR" "$SMOKEDIR"
| `pytest`가 없음 | 가상환경 안에서 `"$VENVDIR/bin/python" -m pip install -e . pytest`를 실행했는지 확인합니다. |
| GitHub API 오류 | 비공개 저장소라면 `GH_TOKEN` 또는 `GITHUB_TOKEN`을 설정합니다. |
| 릴리스 다운로드 없이 테스트하고 싶음 | `QUIVO_LOCAL_SKILLS="$PWD"`를 붙여 local 모드로 실행합니다. |
| 기존 파일과 충돌 | 대상 프로젝트의 기존 `.claude`, `.codex` 파일을 확인한 뒤 필요하면 `--force`를 사용합니다. |
| 기존 파일과 충돌 | 대상 프로젝트의 기존 `.claude/skills`, `.agents/skills` 파일을 확인한 뒤 필요하면 `--force`를 사용합니다. |
| `quivo sync`가 실패 | 대상 프로젝트에 `.quivo-lock.json`이 있는지 확인합니다. 없다면 먼저 `quivo init`을 실행합니다. |

## 다음에 읽을 문서
Expand Down
30 changes: 17 additions & 13 deletions docs/GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,8 +89,8 @@ The choices are:

| Choice | Input | Install location |
|--------|-------|------------------|
| `1` | `claude` | `.claude/skills/` |
| `2` | `codex` | `.codex/prompts/`, `.codex/scripts/` |
| `1` | `claude` | `.claude/skills/q-<name>/` |
| `2` | `codex` | `.agents/skills/q-<name>/` |
| `3` | `both` | Both Claude Code and Codex |

For scripts or docs where you want to avoid the interactive prompt, pass
Expand All @@ -117,9 +117,10 @@ quivo init --agent codex
After installation, the target project should contain files like these:

```text
.claude/skills/<skill-name>/SKILL.md
.codex/prompts/<skill-name>.md
.codex/scripts/<skill-name>/SKILL.md
.claude/skills/q-<skill-name>/SKILL.md
.agents/skills/q-<skill-name>/SKILL.md
CLAUDE.md # managed quivo skill-list block
AGENTS.md # managed quivo skill-list block
.quivo-lock.json
```

Expand Down Expand Up @@ -148,14 +149,19 @@ To refresh skill content to the latest available version, run:
quivo sync
```

Every sync is a **clean reinstall**: quivo first removes the previous install
(every file recorded in `.quivo-lock.json`), then writes the locked skills
fresh at the current layout. Old layouts never accumulate, and skills removed
from the skill source are uninstalled.

To sync a specific project:

```bash
quivo sync --dir /path/to/your/project
```

If existing files cause a conflict, inspect them first. Use `--force` only when
you intentionally want quivo to overwrite installed skill files.
If files quivo did not write itself cause a conflict, inspect them first.
Use `--force` only when you intentionally want quivo to overwrite them.

```bash
quivo sync --force
Expand Down Expand Up @@ -381,8 +387,7 @@ quivo list --dir "$TMPPROJECT"
```

The install path is healthy when the new skill appears under Claude Code's
`.claude/skills/<skill-name>/` and Codex's `.codex/prompts/<skill-name>.md` plus
`.codex/scripts/<skill-name>/`.
`.claude/skills/q-<skill-name>/` and Codex's `.agents/skills/q-<skill-name>/`.

## Install from a local checkout

Expand Down Expand Up @@ -513,9 +518,8 @@ All skills are up to date.
Finally, confirm that representative installed files exist:

```bash
test -f "$SMOKEDIR/.claude/skills/author-skill/SKILL.md"
test -f "$SMOKEDIR/.codex/prompts/author-skill.md"
test -f "$SMOKEDIR/.codex/scripts/author-skill/SKILL.md"
test -f "$SMOKEDIR/.claude/skills/q-author-skill/SKILL.md"
test -f "$SMOKEDIR/.agents/skills/q-author-skill/SKILL.md"
echo "smoke files ok"
```

Expand Down Expand Up @@ -554,7 +558,7 @@ written.
| `pytest` is missing | Run `"$VENVDIR/bin/python" -m pip install -e . pytest` inside the clean setup. |
| GitHub API error | For a private repo, set `GH_TOKEN` or `GITHUB_TOKEN`. |
| You want to test without downloading a release | Run in local mode with `QUIVO_LOCAL_SKILLS="$PWD"`. |
| Existing files conflict | Inspect the target `.claude` or `.codex` files, then use `--force` only if overwriting is intended. |
| Existing files conflict | Inspect the target `.claude/skills` or `.agents/skills` files, then use `--force` only if overwriting is intended. |
| `quivo sync` fails | Make sure the target project has `.quivo-lock.json`. If not, run `quivo init` first. |

## Next documents
Expand Down
6 changes: 3 additions & 3 deletions docs/quivo/fork-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ chordpli/quivo ── fork ──▶ my-company/quivo
│
▼ 엔지니어 머신
quivo init / quivo sync
→ .claude/skills/, .codex/prompts/ ...
→ .claude/skills/, .agents/skills/ ...
```

핵심: 포크하면 업스트림과 끊긴다. 그게 **의도**다 — 회사가 자기 스킬을 완전히 소유한다.
Expand Down Expand Up @@ -145,8 +145,8 @@ quivo init --agent both

| 하네스 | 설치 위치 | 상태 |
|--------|-----------|------|
| Claude Code | `.claude/skills/<name>/SKILL.md` | 지원 |
| Codex CLI | `.codex/prompts/<name>.md` + `.codex/scripts/<name>/` | 지원 |
| Claude Code | `.claude/skills/q-<name>/SKILL.md` | 지원 |
| Codex CLI | `.agents/skills/q-<name>/SKILL.md` (open agent skills 표준) | 지원 |
| (그 외) | 어댑터 추가로 확장 | 로드맵 — [open-source-plan.md](./open-source-plan.md) |

새 하네스 지원은 `src/quivo/adapters/` 에 `BaseAdapter` 구현 1개를 추가하면 된다.
Expand Down
5 changes: 3 additions & 2 deletions docs/quivo/open-source-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,8 +57,9 @@ QUIVO_REPO 환경변수 > 레포 루트 quivo.yml 의 repo: > 내장 기본
### 3.3 멀티 LLM 어댑터 (`src/quivo/adapters/`)

`BaseAdapter` 추상 클래스 + 하네스별 구현:
- `ClaudeAdapter` → `.claude/skills/<name>/SKILL.md` (frontmatter 보존)
- `CodexAdapter` → `.codex/prompts/<name>.md`(frontmatter strip + `# /<name>` 헤더) + `.codex/scripts/<name>/`(sidecar 계약)
- `ClaudeAdapter` → `.claude/skills/q-<name>/SKILL.md` (frontmatter 보존, `name:` 은 `q-` prefix)
- `CodexAdapter` → `.agents/skills/q-<name>/SKILL.md` (frontmatter 보존 — Codex 가 open agent skills 표준에 따라 `.agents/skills/` 를 네이티브 스캔)
- 공통: `CLAUDE.md`/`AGENTS.md` 관리 블록 유지, 레거시 레이아웃 자동 정리 (spec-kit 차용)

새 하네스 = 어댑터 1개 추가. 변환 규칙은 [`reference/agent-adapters.md`](./reference/agent-adapters.md).

Expand Down
6 changes: 3 additions & 3 deletions docs/quivo/permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
권한은 세 단계를 거쳐 흐른다: 스킬이 선언하고 → 조직이 부여하고 → 실행 환경이 강제한다.

1. **SKILL.md 본문 `## Inputs` 섹션 — 선언**
스킬 저자가 자신의 스킬이 필요로 하는 도구/MCP를 자연어로 명시한다. 예: "Linear MCP 호출 필요". 본문에 두는 이유는 헌법 #3 (Parity) — Codex 변환 시 frontmatter는 제거되므로.
스킬 저자가 자신의 스킬이 필요로 하는 도구/MCP를 자연어로 명시한다. 예: "Linear MCP 호출 필요". 본문에 두는 이유는 헌법 #3 (Parity) — validator 비허용 frontmatter 키는 설치 시 `metadata:` 아래로 이동하고, 에이전트가 지시문으로 읽는 보장은 본문뿐이므로.

2. **`.quivo/policy.md` — 부여 의도**
조직 owner가 어떤 스킬에 어떤 권한을 줄지 마크다운 표로 선언한다. 예: "linear-split → linear_mcp 허용". 부여되지 않은 권한은 허용되지 않은 것이다.
Expand Down Expand Up @@ -42,7 +42,7 @@
- **MUST**: MCP 사용 시 `**MCP**:` 접두사로 표기. lint-skills 가 이 패턴을 검색해 manifest 생성.
- **MUST**: 특정 bash 명령이 필요하면 `**Bash**:` 접두사 + 명령 패턴.
- **MUST NOT**: 본문 어딘가에 묻혀서 적지 말 것. `Inputs` 섹션 외에 흩어지면 lint·정책 매핑이 어려움.
- frontmatter 에 `permissions:` 같은 9번째 필드를 추가하지 않는다 — Codex 변환 시 frontmatter 가 사라지기 때문 (헌법 #3).
- frontmatter 에 `permissions:` 같은 9번째 필드를 추가하지 않는다 — validator 비허용 키라 설치 시 `metadata:` 아래로 이동해 에이전트가 읽지 않기 때문 (헌법 #3).

---

Expand Down Expand Up @@ -120,7 +120,7 @@
```

```jsonc
// .codex/* (Codex CLI 권한 설정 — Codex CLI 매뉴얼 따름)
// ~/.codex/config.toml (Codex CLI 권한·스킬 설정 — Codex CLI 매뉴얼 따름)
```

### v0.2 — 자동
Expand Down
Loading
Loading