pgg

pgg is a pnpm-based workspace that turns the .codex, AGENTS.md, and poggn workflow into a reusable CLI and dashboard product.

pgg는 .codex, AGENTS.md, poggn 워크플로를 재사용 가능한 CLI와 dashboard 제품으로 정리한 pnpm workspace입니다.

Quick Start

ko

이 저장소에서 바로 동작을 확인하려면 아래 순서로 진행합니다.

pnpm install
pnpm build
pnpm link --global
pgg init --cwd /tmp/pgg-sample --provider codex --lang ko --auto on --teams off
pgg git --cwd /tmp/pgg-sample --value on
pgg teams --cwd /tmp/pgg-sample --value on
pgg status --cwd /tmp/pgg-sample
pgg dashboard --cwd /tmp/pgg-sample --snapshot-only

repo root에서 global link 없이 직접 실행하려면 local workspace 경로 node packages/cli/dist/index.js ...를 사용할 수 있습니다.

packages/cli/README.md는 package 내부 구조를 볼 때 참고하는 보조 문서입니다.

en

To use pgg from this repository, build the workspace at the repo root and run pnpm link --global from the root package.

Without global linking, you can still execute the local workspace entrypoint: node packages/cli/dist/index.js ....

packages/cli/README.md is a supporting note for the package internals.

Commands

ko

• pgg init: 대상 프로젝트에 .codex, AGENTS.md, poggn, manifest를 생성하고 registry에 등록합니다.
• pgg update: generator 관리 자산을 현재 버전에 맞게 다시 동기화합니다.
• pgg lang: ko, en 전환과 관련 generated asset 반영을 수행합니다.
• pgg auto: on, off 전환과 auto mode 관련 문서 상태를 반영합니다.
• pgg teams: on, off 전환과 teams mode 기반 자동 orchestration 계약을 반영합니다.
• pgg git: on, off 전환과 QA 이후 git publish 자동화 설정을 반영합니다.
• pgg status: current-project의 active topic 상태와 다음 workflow 추천을 JSON으로 출력합니다.
• pgg dashboard: snapshot export 또는 로컬 dashboard 실행을 수행합니다.
• 선택형 TTY 인터랙션은 방향키와 Enter 기반 공통 메뉴를 사용합니다.
• interactive 변경 명령은 변경 경로 또는 no-op/cancel 상태를 출력한 뒤 종료합니다.

en

• pgg init: creates .codex, AGENTS.md, poggn, and the local manifest for a target project.
• pgg update: resynchronizes generator-managed assets to the current product shape.
• pgg lang: switches between ko and en and updates generated assets.
• pgg auto: switches workflow auto mode between on and off.
• pgg teams: switches teams mode between on and off and controls expert-based automatic orchestration.
• pgg git: switches post-QA git publish automation between on and off.
• pgg status: prints active-topic status plus recommended next workflow for the current project as JSON.
• pgg dashboard: exports a snapshot or launches the local operations dashboard.
• Interactive TTY choices use a shared Up/Down plus Enter menu.
• Interactive change commands print changed paths or a no-op/cancel status before exit.

Workflow

ko

pgg는 topic을 poggn/active/<topic> 아래에서 관리하고 core workflow를 아래 순서로 진행합니다.

1. pgg-add: proposal, 사용자 질문 기록, 전문가 attribution review 생성
2. pgg-plan: plan, task, spec, plan/task review 생성
3. pgg-code: 구현과 diff, code review 기록
4. pgg-refactor: 레거시 제거와 구조 개선, refactor review 기록
5. pgg-qa: qa/report.md 검증과 archive 판정

필요한 topic에서만 여는 optional audit는 다음과 같습니다.

• pgg-token: workflow 자산, handoff, helper, generated 문서의 token 비용을 점검할 때만 실행하는 optional audit
• pgg-performance: 성능 민감 변경이나 선언된 verification contract가 있을 때만 실행하는 optional audit

pgg teams가 on이면 각 단계는 정의된 전문가 roster를 기준으로 자동 orchestration을 사용하고, handoff는 state/current.md와 pgg-state-pack.sh 중심으로 최소화합니다. 현재 프로젝트 내부 문서 생성, 확인, 기록 절차는 core workflow 전반과 필요한 optional audit 안에서 자동 처리하며, proposal 단계에서 사용자 질문 기록과 archive_type(feat, fix, docs, refactor, chore, remove)를 확정합니다. 모든 pgg-* flow 문서와 state/history 문구, commit message, pgg가 생성하거나 수정하는 코드 주석은 pgg lang을 따르며, 사용자가 작성한 기존 주석은 범위 밖에서 일괄 번역하지 않습니다. pgg-code와 pgg-refactor는 공통 필수 구현 기준을 따르며, pgg git=on이면 task 완료마다 .codex/sh/pgg-stage-commit.sh로 {convention}: {version}.{commit message} 형식의 stage commit을 남깁니다. commit message는 pgg lang=ko면 한글, pgg lang=en이면 영어를 사용합니다. pgg-token과 pgg-performance는 plan/state/qa의 audit applicability가 required일 때만 후속 gate에서 강제됩니다. pgg가 생성·관리하는 executable .codex/sh/*.sh helper만 workflow 내부 trusted script로 보고 추가 허락 없이 실행합니다. 대상 프로젝트 검증은 선언된 current-project verification contract로만 다루며, contract가 없으면 QA는 추론 실행 대신 manual verification required를 기록합니다.

검증이 끝난 topic만 version 기록과 함께 poggn/archive/<topic>으로 이동하며, 누적 version ledger는 append-only poggn/version-history.ndjson에 저장됩니다. pgg git이 on이면 archive 뒤에 ai/<archive_type>/<target-version>-<short-name>에서 release/<target-version>-<short-name>으로 승격하는 publish 자동화가 이어지고, remote release branch가 없으면 first push는 upstream 구성 경로로 처리되며 main 직접 push는 금지됩니다. 이때 archive helper는 QA 산출물 뒤 변경이 남으면 먼저 localized versioned qa completion commit을 만들고, publish helper는 state/current.md 또는 qa/report.md의 ## Git Publish Message 섹션에서 - title:, - why:, - footer:를 읽어 {convention}: {version}.{commit message} 형식, 제목 50자 이하, 명령형 금지, 마침표 금지, 상세 body, 한 커밋 = 하나의 의도, 로그가 곧 문서 규칙을 강제합니다. archive_type는 change category와 commit convention을 유지하고, semver는 별도 version_bump(major|minor|patch)와 target_version으로 계산합니다. short_name은 full topic slug fallback이 아니라 1~3 token의 concise alias여야 하며, working branch는 QA 완료 후 release branch 승격이 성공한 뒤에만 제거됩니다. pgg update는 generator-managed 자산을 다시 동기화하지만, 기존 version ledger 내용은 보존해야 합니다.

en

Topics live under poggn/active/<topic> and move through the following core workflow before archive.

1. pgg-add: create the proposal, the user-question record, and the attributed proposal review
2. pgg-plan: create the plan, task, spec, and plan/task reviews
3. pgg-code: implement the change and record diffs plus the code review
4. pgg-refactor: remove legacy code, improve structure, and record the refactor review
5. pgg-qa: validate qa/report.md and decide archive readiness

Optional audits are opened only for topics that explicitly need them.

• pgg-token: an optional audit used only when workflow assets, handoff, helpers, or generated docs need token-cost review
• pgg-performance: an optional audit used only when the topic has performance-sensitive changes or a declared verification contract

When pgg teams is on, each stage can use expert-roster-based automatic orchestration and minimized handoff via state/current.md plus pgg-state-pack.sh. Stage-local confirmations, records, and generated documents are handled automatically only when the work stays inside the current project across the core workflow and any required optional audits, and the proposal stage records the user questions plus resolves archive_type (feat, fix, docs, refactor, chore, remove). All pgg-* flow documents, state/history text, commit messages, and pgg-generated or pgg-modified code comments follow pgg lang; existing user-authored comments are not bulk-translated outside the task scope. pgg-code and pgg-refactor share the mandatory implementation criteria and, when pgg git=on, record task completion commits through .codex/sh/pgg-stage-commit.sh in the {convention}: {version}.{commit message} form. Commit message text is Korean for pgg lang=ko and English for pgg lang=en. pgg-token and pgg-performance become gate-enforced only when the plan/state/QA audit applicability marks them as required. Only pgg-generated and managed executable .codex/sh/*.sh helpers are trusted workflow scripts that can run without extra approval. Project verification uses declared current-project verification contracts only; when no contract exists, QA records manual verification required instead of guessing framework commands.

Only QA-passed topics move to poggn/archive/<topic>, and archive version history is appended to the append-only poggn/version-history.ndjson ledger. When pgg git is on, archive handling continues from ai/<archive_type>/<target-version>-<short-name> into release/<target-version>-<short-name> publish automation, first publish uses an upstream-configuring path when the remote release branch is missing, and direct pushes to main are blocked. When QA artifacts leave additional changes, the archive helper records a localized versioned qa completion commit first, then the publish helper reads - title:, - why:, and - footer: from ## Git Publish Message in state/current.md or qa/report.md and enforces the {convention}: {version}.{commit message} subject format, 50-character limit, non-imperative phrasing, no period, detailed body content, one commit per intent, and logs as documentation. archive_type remains the change category and commit convention while semver is derived from a separate version_bump (major|minor|patch) plus target_version. short_name must stay a concise 1-3 token alias instead of falling back to the full topic slug, and the working branch is removed only after successful release promotion. pgg update resynchronizes generated assets without resetting existing version ledger entries.

Project Structure

ko

• .codex/: workflow 규칙, skill, shell helper
• poggn/: active/archive topic 문서, 상태 기록, version history
• AGENTS.md: Codex 작업 규칙
• packages/core: generator, manifest, registry, analyzer
• packages/cli: pgg CLI 엔트리
• apps/dashboard: React, React Query, React Flow, Zustand 기반 운영 UI

en

• .codex/: workflow rules, skills, and shell helpers
• poggn/: active and archived topic records plus version history
• AGENTS.md: Codex-specific working rules
• packages/core: generators, manifest IO, registry helpers, analyzers
• packages/cli: the pgg CLI entrypoint
• apps/dashboard: the local React operations dashboard

Dashboard

ko

dashboard는 현재 프로젝트와 registry snapshot을 읽어 topic 상태, workflow, 언어, auto mode, git mode, dashboard 기본 포트를 보여줍니다.

로컬 개발에서는 아래 스크립트를 사용할 수 있습니다.

pnpm dev:dashboard

또는 CLI를 통해 snapshot 생성과 함께 실행할 수 있습니다.

node packages/cli/dist/index.js dashboard --cwd /path/to/project --host 127.0.0.1 --port 4173

en

The dashboard reads the current project and registry snapshot to show topic health, workflow state, language, auto mode, git mode, and the saved dashboard port.

Use pnpm dev:dashboard for local UI work, or run the CLI dashboard command to generate and serve project data.

Notes

ko

• 현재 provider 구현 범위는 codex입니다.
• pgg teams의 기본값은 off이며, on일 때만 stage별 자동 orchestration이 활성화됩니다.
• README.md는 generator가 관리하는 문서 자산입니다.
• poggn/version-history.ndjson는 archive 시 한 줄씩 append 되는 NDJSON ledger입니다. 이 형식은 마지막 entry 조회와 줄 단위 복구가 단순합니다.
• pnpm test는 pgg workspace 자체 계약을 재실행하는 최소 공식 runner이며, 현재는 packages/core 회귀를 우선 고정합니다.
• Spring Boot 같은 프레임워크 검증은 선언적 contract/preset opt-in일 때만 자동화 후보가 되며, 기본값은 추론 실행이 아니라 manual verification required입니다.
• Git Publish Message의 footer가 비어 있으면 helper는 Refs: <topic> fallback을 사용하며, 제목은 {convention}: {version}.{commit message} 형식을 따릅니다.
• major는 기존 사용자 workflow, helper 계약, generated file 계약, expected output format이 깨질 때 사용하고, minor는 compatible 기능 추가/변경, patch는 compatible 버그/문서/소규모 refactor/chore 기본값입니다.
• project-level README 생성과 pgg update 직접 연동은 후속 범위입니다.

en

• The current provider implementation is limited to codex.
• pgg teams defaults to off, and stage-level automatic orchestration is enabled only when it is on.
• This README.md is intended to be a generator-managed document asset.
• poggn/version-history.ndjson is an NDJSON ledger that appends one archive record per line, which keeps last-entry lookups and line-level recovery simple.
• pnpm test is the minimum official runner for re-running pgg workspace contracts, starting with packages/core regressions.
• Framework verification such as Spring Boot is opt-in through declared contracts or presets; the default is manual verification required, not guessed execution.
• When Git Publish Message.footer is empty, the helper falls back to Refs: <topic>, and titles should use {convention}: {version}.{commit message}.
• Use major when an existing user workflow, helper contract, generated file contract, or expected output format breaks; use minor for compatible feature additions/changes and patch for compatible bugs, docs, and small refactor/chore updates by default.
• Project-level README generation and direct pgg update wiring remain future work.