sham-agent-tools

Claude Code와 Codex에서 공통으로 사용하는 개발 workflow plugin marketplace다. GitHub Issue 정의, TDD, 품질 검증, Git, 문서화와 workflow 개선 절차를 여러 프로젝트에서 재사용할 수 있다.

Workflow

GitHub Issue
  → spsc
  → red → green → refactor
  → quality-check 또는 fix
  → commit
  → pr
  → GitHub Actions CI

• GitHub Issue가 작업 범위와 완료 기준의 기준점이다.
• quality-check는 파일을 수정하지 않는 사전 검사다.
• fix는 format과 lint 등 안전한 기계적 수정만 수행한다.
• GitHub Actions와 branch protection 또는 ruleset이 최종 merge gate 역할을 한다.
• Skill 본문은 Agent Skills 공통 규격을 사용하고 플랫폼별 manifest와 hooks만 분리한다.

Claude Code 설치

GitHub 저장소 이름을 sham-agent-tools로 변경한 후 다음 명령을 사용한다.

/plugin marketplace add GulSam00/sham-agent-tools
/plugin install til-notion@sham-agent-tools
/plugin install tdd-workflow@sham-agent-tools
/plugin install git-workflow@sham-agent-tools
/plugin install issue-workflow@sham-agent-tools
/plugin install docs-tools@sham-agent-tools
/plugin install workflow-observer@sham-agent-tools

로컬 clone에서 테스트할 때:

/plugin marketplace add ./

갱신:

/plugin marketplace update sham-agent-tools
/reload-plugins

Codex 설치

Marketplace 등록:

codex plugin marketplace add GulSam00/sham-agent-tools
codex plugin marketplace upgrade sham-agent-tools

ChatGPT 데스크톱 앱을 다시 시작한 뒤 Plugins에서 Sham Agent Tools Marketplace를 선택하고 필요한 plugin을 설치한다.

로컬 clone은 다음처럼 등록한다.

codex plugin marketplace add ./

Skill 호출

목적	Claude Code	Codex
Skill 탐색	/ 또는 plugin Skill 목록	/skills
Red 단계	/tdd-workflow:red	$tdd-workflow:red
품질 검사	/tdd-workflow:quality-check	$tdd-workflow:quality-check
커밋	/git-workflow:commit	$git-workflow:commit
관찰 결과 검토	/workflow-observer:review-observations	$workflow-observer:review-observations

Skill 내부에서는 플랫폼 호출 문법을 사용하지 않는다. 다음 Skill 이름과 handoff 상태만 전달한다.

Plugin 목록

Plugin	내용
til-notion	기존 Notion 페이지에 구조화된 TIL 추가
issue-workflow	GitHub Issue 생성과 작업 범위 정의
tdd-workflow	프로젝트 탐지형 red, green, refactor, quality-check, fix와 setup-ci
git-workflow	GitHub Issue 번호 기반 commit과 pull request 생성
docs-tools	유지보수 HTML과 실제 화면 캡처 가이드 생성
workflow-observer	로컬 workflow 관찰, 개선 후보 검토와 승인 기반 draft PR

Workflow Observer

Observer는 모델을 호출하지 않는 command hooks와 Node.js 규칙 엔진으로 동작한다.

1. 프롬프트 원문 대신 hash, 최대 12개 키워드, tool 또는 Skill 결과와 session metadata를 로컬에 저장한다.
2. 충분한 표본에서 반복 실패나 반복 workflow가 발견되면 개선 후보를 만든다.
3. 사용자가 후보를 검토하고 명시적으로 승인한 경우에만 Issue, branch, 변경, push와 draft PR을 진행한다.

플랫폼별 수집 차이:

기능	Claude Code	Codex
프롬프트 신호	UserPromptSubmit	UserPromptSubmit
Skill 결과	PostToolUse의 Skill	명시적 $skill과 tool 흐름
실패 신호	PostToolUseFailure	지원되는 turn/tool 신호만 사용
분석 시점	SessionEnd	Stop
실행 방식	빈번한 기록은 async	동기 command hook

두 adapter는 동일한 observer event schema와 분석·추천 저장소를 사용한다. 지원되지 않는 신호를 성공이나 실패로 추측하지 않는다.

환경 설정:

# 모든 기록 비활성화
export WORKFLOW_OBSERVER_ENABLED=0

# 키워드 fingerprint 저장 비활성화
export WORKFLOW_OBSERVER_KEYWORDS=0

# 기본 5,000개인 최대 event 수 변경
export WORKFLOW_OBSERVER_MAX_EVENTS=2000

프롬프트 원문, transcript 경로, 소스 코드, tool 입력, 절대 프로젝트 경로와 환경 변수는 기록하거나 외부로 자동 전송하지 않는다. 기록과 규칙 분석은 모델 토큰을 사용하지 않고, 리뷰·적용 Skill을 실행할 때만 일반적인 모델 토큰이 사용된다.

Requirements

• issue-workflow, git-workflow: 인증된 GitHub CLI (gh)
• setup-ci: GitHub Actions를 사용할 GitHub 저장소
• til-notion: Claude Code 또는 Codex에 연결된 Notion MCP 또는 connector
• TDD skills: 대상 프로젝트가 사용하는 test runner와 package/build tool
• workflow-observer: Node.js

Repository 구조

.claude-plugin/marketplace.json       # Claude Code marketplace
.agents/plugins/marketplace.json      # Codex marketplace
plugins/<plugin>/
├── .claude-plugin/plugin.json        # Claude Code adapter
├── .codex-plugin/plugin.json         # Codex adapter
├── skills/                           # Shared Agent Skills
├── references/                       # Shared policies and references
├── scripts/                          # Shared deterministic tools
└── hooks/                            # Platform adapters when required

새 Skill 또는 Plugin 추가

1. skills/<skill-name>/SKILL.md에는 name과 description만 포함하는 공통 frontmatter를 사용한다.
2. Claude와 Codex plugin manifest에 동일한 plugin 이름과 version을 반영한다.
3. 두 Marketplace에 같은 plugin 목록과 source를 등록한다.
4. 플랫폼 전용 호출 문법은 README에만 작성한다.
5. validator, 관련 테스트와 두 플랫폼 plugin 검증을 실행한다.

Validation

node scripts/validate-marketplace.mjs
node scripts/validate-marketplace.mjs --base HEAD
node --test plugins/tdd-workflow/scripts/tests/detect-project.test.mjs
node --test plugins/workflow-observer/scripts/tests/workflow-observer.test.mjs
claude plugin validate .

GitHub Actions는 다음 항목을 검사한다.

• Claude와 Codex Marketplace JSON
• 두 plugin manifest의 이름과 version 일치
• Codex source, installation, authentication과 category 정책
• 공통 Skill frontmatter와 supporting file 참조
• 플랫폼별 hook event와 async 정책
• 변경된 plugin의 version 증가
• TDD project detector와 workflow observer 테스트

Version 규칙

Skill, reference, template, script, hook 또는 manifest를 수정하면 해당 plugin의 Claude와 Codex manifest version을 함께 올린다.

• 문구나 오타 수정: patch
• 동작·절차 변경 또는 Skill 추가: minor
• 호출 정책, 공개 schema 또는 호환성 변경: major

Marketplace 이름, plugin 목록 또는 source 구조가 바뀌면 두 Marketplace의 version 또는 release metadata도 함께 검토한다.

Repository 이름 변경

이 작업 트리는 아직 기존 Git remote를 가리킬 수 있다. GitHub에서 저장소를 sham-agent-tools로 변경한 후 로컬 remote를 갱신한다.

git remote set-url origin https://github.com/GulSam00/sham-agent-tools.git