WaterplanAI/agentic-config

pi 패키지와 Claude Code 플러그인을 통한 프로젝트 불가지론적(Project-agnostic)이고 조립 가능한 AI 워크플로우 자동화.

현재 공개된 릴리스 태그(release tag)를 통한 기본 설치 방법:

pi install "git:github.com/WaterplanAI/agentic-config@v0.3.0" -l

-l 플래그는 이를 로컬 프로젝트 설정(local project config)에 설치합니다. 전역/사용자 설치(global/user install)를 원할 경우 -l을 제거하십시오.

팀 단위 작업 및 자동화를 위해서는 배포(rollout)의 재현성(reproducible)을 유지할 수 있도록 커밋된 .pi/settings.json 파일에 태그가 지정된 git 참조(git ref)를 사용하는 것을 권장합니다.

로컬 테스트 또는 개발을 위해서는 태그 대신 브랜치 참조(branch ref)를 사용하십시오. 예시:

pi install "git:github.com/WaterplanAI/agentic-config@main" -l

SSH 전송(SSH transport)을 선호하는 경우, 동일한 저장소와 참조에 대해 상응하는 SSH git 소스를 사용하십시오.

현재의 git 루트 설치는 배포된 전체 pi 표면(pi surface)을 노출합니다. 개별 패키지 루트 설치(Individual package-root installs)는 로컬 패키지 개발 및 검증에 여전히 유용합니다. npm 발행(npm publication)은 향후 과제로 남아 있습니다.

claude plugin marketplace add WaterplanAI/agentic-config
# 개발 브랜치의 경우: `claude plugin marketplace add </path/to/dev/branch>` 또는 `./dev.sh` 실행
claude plugin install ac-workflow@agentic-plugins
...

참고: 서드파티 마켓플레이스(third-party marketplaces)에 대한 자동 업데이트(Auto-updates)는 기본적으로 비활성화되어 있습니다. /plugins를 통해 활성화하십시오.

Marketplaces > agentic-plugins > Enable auto-update를 선택하여 새로운 릴리스와 자동으로 동기화되도록 설정하십시오.

pi 및 Claude Code 설정에 대해서는 Getting Started를 참조하십시오.

Pi는 현재 git 참조로부터 설치 가능한 검증된 루트 엄브렐러 패키지(root umbrella package)를 통해 지원되며, 개발 및 검증을 위한 로컬 패키지 루트 설치도 지원합니다. 패키지별 npm 표면(per-package npm surface)을 발행하는 것은 향후 과제로 남아 있습니다.

팀의 경우, 릴리스 태그에 고정된(pinned) 커밋된 .pi/settings.json을 사용하는 것을 권장합니다. 로컬 테스트 및 개발을 위해서는 상황에 따라 브랜치 참조(branch refs) 또는 직접적인 로컬 패키지 경로를 사용하십시오.

agentic-config는 Pi를 위한 서드파티 패키지(third-party packages)를 제공합니다. CLI, 패키지 로더(package loader), 확장 API(extension API), 런타임(runtime)을 포함한 Pi 자체는 pi.dev 및 badlogic/pi-mono에서 업스트림(upstream)으로 유지 관리됩니다. 여기서 제공되는 패키지 인터페이스는 필요한 경우 @mariozechner/pi-coding-agent 및 @mariozechner/pi-ai와 같은 업스트림 Pi API를 임포트(import)합니다.

소스 링크 및 런타임 소유권 경계에 대해서는 Upstream Pi attribution을 참조하십시오.

@agentic-config/pi-ac-workflow 내부에서 런타임 소유권은 의도적으로 설계되었습니다. pimux는 패키지 소유의 tmux 제어 평면(control plane)이며, ac-workflow-mux, ac-workflow-mux-ospec, ac-workflow-mux-roadmap은 그 위에 구축된 구조화된 래퍼(wrapper)입니다. 일반적인 장기 실행(long-lived) tmux 작업은 pimux에 머무릅니다. 제공되는 pi 패키지는 더 이상 별도의 관리형 에이전트(managed-agent) 인터페이스를 노출하지 않습니다.

빠른 선택 가이드:

• 일반적인 장기 실행 tmux 워커(worker), 소규모 팀, 또는 검사 가능한 non-mux 계층 구조가 필요한 경우: pimux 사용
• scout/planner/worker 오케스트레이션(orchestration)이 필요한 경우: ac-workflow-mux 사용
• 하나의 명시적인 스펙 단계(spec-stage) 소유자가 필요한 경우: ac-workflow-mux-ospec 사용
• roadmap -> phase -> stage 중첩 구조가 필요한 경우: ac-workflow-mux-roadmap 사용

pimux Workflow Topologies를 참조하십시오.

기본 git-tag 설치 경로, 브랜치 기반 개발 설치, 로컬 패키지 루트(package-root) 테스트 및 향후 npm 배포에 관한 사항은 Pi Package Adoption Guide를 참조하십시오.

pi 패키지 및 Claude Code 플러그인으로 제공되는 중앙 집중식 구성 시스템(centralized configuration system)입니다.

향후 릴리스에서는 동일한 플러그인 접근 방식을 추가 도구(Cursor, Codex CLI, Gemini CLI, Antigravity)로 확장할 예정입니다.

핵심 원칙:

프로젝트 불가지론적 (Project-agnostic) -- 수정 없이 모든 코드베이스에서 작동합니다.
조립 가능 (Composable) -- 기술(skills)이 다른 기술을 호출하여 복합적인 자동화를 생성합니다.
네이티브 배포 인터페이스 (Native distribution surfaces) -- pi install을 통한 pi; claude plugin install을 통한 Claude Code

플러그인 (Plugin)	중점 사항 (Focus)	기술 (Skills)
ac-workflow	워크플로 사양 (Spec workflow), pimux 기반 오케스트레이션 (orchestration)	6
ac-git	Git 자동화, PR (Pull Requests), 릴리스 (releases)	7
ac-qa	QA (Quality Assurance), E2E (End-to-End) 테스트, 브라우저 자동화 (browser automation)	7
ac-tools	유틸리티 (Utilities), 통합 (integrations), 부트스트랩 (bootstrap)	17
ac-meta	메타 프롬프팅 (Meta-prompting), 자기 개선 (self-improvement)	2
ac-safety	보안 가드레일 (Security guardrails) (자격 증명 (credential), 쓰기 범위 (write-scope), 파괴적 bash (destructive-bash), 공급망 (supply-chain), playwright)	2
ac-audit	도구 감사 로깅 (Tool audit logging) (JSONL 추가 전용 로그 (append-only log))	1

• 시작하기 (Getting Started) -- 설치, 설정, 첫 사용
• 플러그인 카탈로그 (Plugin Catalog) -- 구성 패턴 (composition patterns)을 포함한 42개 전체 기술
• pimux 워크플로 토폴로지 (pimux Workflow Topologies) -- pimux, mux, ospec, 그리고 로드맵 계층 구조 가이드
• 배포 가이드 (Distribution Guide) -- pi git-tag 설치, Claude 마켓플레이스 출시, dev 브랜치 설치, 그리고 향후 npm 관련 참고 사항
• Pi 패키지 채택 가이드 (Pi Package Adoption Guide) -- 주요 git-tag 설치, 브랜치 기반 dev 설치, 로컬 패키지 루트 테스트, 그리고 향후 npm 배포 관련 참고 사항
• 업스트림 Pi 귀속 (Upstream Pi attribution) -- 업스트림 Pi 참조 및 agentic-config 패키지 소유권 경계
• 마이그레이션 가이드 v0.2.0 (Migration Guide v0.2.0) -- v0.1.x에서 마이그레이션
• 레거시 삭제 (v0.1.x) (Uninstall Legacy (v0.1.x)) -- 레거시 심볼릭 링크 (symlink) 연결 제거
• 전체 문서 인덱스 (Full Documentation Index)

Claude Code MUX 워크플로 (ac-workflow 플러그인)는 Task(run_in_background=True)를 통해 백그라운드 에이전트 (background agents)에게 작업을 위임합니다. 백그라운드 에이전트는 대화형 권한 프롬프트 (interactive permission prompts)를 표시할 수 없습니다 -- 승인되지 않은 모든 도구는 자동으로 거부됩니다. pi에서 mux 제품군은 패키지 소유의 pimux 런타임 (runtime)을 사용합니다; pimux 워크플로 토폴로지를 참조하십시오.

권장 사항: MUX 워크플로를 위해 Claude Code를 --dangerously-skip-permissions 옵션과 함께 실행하십시오:

claude --dangerously-skip-permissions

또는, CLI를 통해 특정 도구를 사전 승인하십시오:

claude --allowedTools "Skill Bash Read Write Edit Grep Glob"

이 리포지토리의 모든 플러그인은 모든 도구 권한이 활성화된 상태에서 설계 및 테스트되었습니다.

배포 전 로컬 pi 패키지 테스트를 위해서는 Pi 패키지 채택 가이드부터 시작하십시오.