gitea-agent/harness/agents/impl/skills/gitea-issue-implementation/SKILL.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
gitea-issue-implementation	승인된 Gitea Issue를 구현·검증하고 Gitea PR로 전달한다.	0.2.0	genichin, Hermes Agent	MIT	linux	hermes tags related_skills gitea implementation worktree testing pull-request

Gitea Issue Implementation

승인된 Gitea Discovery와 pinned repository revision을 근거로 Issue별 persistent worktree에서 요구 문서, source와 test를 구현하고 검증한 뒤 Issue 전용 branch와 Gitea PR로 전달한다. Repository cache와 worktree 규칙은 Repository cache 운영 지침, 문서 형식은 docs/ 아래 각 문서 유형의 README와 TEMPLATE만 정본으로 사용한다. Exact Issue 구현 요청은 승인된 범위의 commit, 일반 push와 PR 생성을 승인하지만 merge, force-push, Issue close, release 또는 deployment를 승인하지 않는다.

사용 시점

다음과 같이 exact repository와 Issue를 지정해 구현을 요청받았을 때 사용한다.

<owner>/<repository> 이슈 #<number>를 구현하라

이 요청은 현재 authoritative Issue body를 구현 대상으로 승인하고 다음 작업을 허용한다.

• canonical Issue worktree 생성 또는 유효한 기존 worktree 재사용
• 승인된 범위의 요구 문서, source, test와 repository 설정 수정
• synthetic fixture와 test-only credential을 사용한 build, test, lint와 정적 검증
• 구현 결과와 검증 evidence의 local 보존
• 승인된 diff만 포함하는 local commit 생성
• Issue 전용 remote branch의 신규 생성과 non-force push
• Target repository write 권한이 없을 때 authenticated identity 소유 fork 생성·재사용과 cross-repository PR 전달
• default branch를 base로 하는 Gitea PR 생성과 생성 결과 readback
• PR 번호 확정 후 요구 문서의 구현 PR: 미정을 실제 번호 또는 URL로 갱신하는 후속 commit과 non-force push

다음 작업은 요청 문구에 별도로 명시되지 않으면 승인되지 않는다.

• force-push, rebase, amend 또는 다른 history rewrite
• default branch나 기존 비전용 remote branch로의 push
• PR merge, close, review, reviewer 지정 또는 승인 범위를 바꾸는 수정
• Issue comment, body, title, state, label, assignee 또는 milestone 변경
• release, package 또는 deployment 게시

Discovery 작성·검토, 미해결 요구사항 선택, 단순 repository 조사 또는 이미 구현된 변경의 독립 PR review에는 사용하지 않는다.

정본과 승인 gate

구현을 시작하려면 현재 Issue body가 다음을 모두 충족해야 한다.

• 첫 줄이 exact <!-- gitea-agent:discovery-draft/v2 --> marker다.
• 요약, 문제, 포함 범위, 제외 범위, 제약 조건, 확정된 결정, 저장소 근거, 문서 영향 및 산출물, 미해결 질문을 판독할 수 있다.
• 미해결 질문이 exact 없음이거나 동등하게 미해결 결정이 없음을 명확히 나타낸다.
• pinned source revision이 full commit SHA로 하나만 확정돼 있다.
• 구현 산출물의 exact 경로와 요구사항 ID를 안전하게 결정할 수 있다.
• 서로 충돌하는 결정, 선택되지 않은 선택지, placeholder 또는 실제 credential이 없다.

정확한 구현 요청은 해당 시점의 유효한 current body에 대한 구현 승인이다. 그러나 미해결 질문, malformed Discovery, 결정 충돌, 불명확한 범위 또는 credential 노출이 있으면 사용자의 의도를 추측하지 않고 worktree나 repository file을 변경하지 않는다.

Issue body와 updated_at을 immutable approval snapshot으로 보존한다. body의 exact UTF-8 SHA-256 digest를 terminal로 계산하며 식별자나 digest를 임의로 정규화하지 않는다. 구현 중 authoritative Issue가 snapshot과 달라지면 새 내용을 자동 채택하지 않고 drift로 중단한다.

Lock과 권한 경계

모든 cache, lock, path, credential, worktree 생성·재사용·제거 규칙은 작업할 때마다 read_file로 operations/repository-cache.md를 새로 읽어 적용한다. 이 스킬의 요약이 canonical 문서를 완화하거나 대체하지 않는다.

• Issue workflow 전체에서 exact issue-<number>.lock을 유지한다.
• Cache 초기화·fetch·ref 검증과 worktree 등록 변경에는 canonical 순서로 repository lock을 추가 획득한다.
• 일반 편집과 test에는 Issue lock만 유지한다.
• 다른 Issue worktree나 다른 checkout을 읽기·수정·정리하지 않는다.
• lock을 획득할 수 없거나 현재 실행이 lock 순서를 증명할 수 없으면 fail-closed한다.
• 종료, 오류와 중단 경로에서 현재 실행이 획득한 lock만 역순으로 해제한다.

절차

1. Target과 identity 고정

1. 요청에서 exact owner, repository와 Issue 번호를 추출하고 각각 canonical identifier 규칙으로 검증한다.
2. Issue lock을 획득한다.
3. Gitea MCP get_me로 현재 impl role identity를 확인한다.
4. Gitea MCP로 exact repository metadata, default branch와 SHA, Issue 전체 필드와 전체 comment baseline을 읽는다.
5. title, body, state, labels, assignees, milestone, updated_at, comment cardinality와 body digest를 immutable approval snapshot으로 기록한다.

완료 조건: authenticated identity, exact target과 재현 가능한 approval snapshot이 모두 존재한다.

2. Discovery와 산출물 계약 추출

1. 승인 gate로 current body를 검증한다.
2. 포함 범위, 제외 범위, 제약 조건과 확정된 결정을 중복 없이 추출한다.
3. 각 문서의 조치, exact path와 필수 내용을 추출한다. 영향 없음인 문서를 생성하지 않는다.
4. 사용자 관찰 가능 동작, 실패 동작, 보안 불변조건, 호환성 조건과 외부 write 경계를 acceptance matrix로 만든다.
5. 각 acceptance criterion에 예정된 문서, source 위치와 검증 test를 연결한다. 연결할 수 없는 criterion이 있으면 구현 전에 중단한다.

완료 조건: 모든 확정된 결정과 산출물이 acceptance matrix의 한 항목 이상에 대응하고, 제외 범위가 구현 항목에 포함되지 않는다.

3. Cache 검증과 base 결정

1. operations/repository-cache.md를 새로 읽는다.
2. Canonical 절차로 cache를 초기화하거나 기존 cache를 검증한다. malformed cache를 삭제, reset, chmod, chown 또는 다른 repository로 교체하지 않는다.
3. Issue lock 아래 repository lock을 획득해 exact origin에서 prune/fetch하고 Gitea default branch SHA와 local ref 일치를 검증한다.
4. Discovery pinned SHA가 cache에 존재하는 commit object이고 Issue가 주장한 revision과 exact-match하는지 확인한다.
5. Pinned SHA와 current default branch SHA가 같으면 이를 base로 확정한다.
6. 두 SHA가 다르면 pinned revision부터 current default branch까지의 commit과 변경 파일을 조사한다. 변경이 Discovery 근거, 요구 문서 ID·경로, 대상 API, test contract 또는 acceptance criteria를 무효화하지 않는다는 근거가 있을 때만 current default branch SHA를 base로 사용한다.
7. 변경이 material하거나 요구사항과 충돌하거나 안전하게 판정할 수 없으면 worktree를 만들거나 수정하지 않고 renewed Discovery가 필요하다고 보고한다.

완료 조건: Gitea와 local에서 확인된 full base SHA, 선택 근거와 pinned-to-base 차이 판정이 기록돼 있다.

4. Worktree 생성 또는 재사용

1. Approval snapshot이 아직 current Issue와 exact-match하는지 다시 읽는다.
2. operations/repository-cache.md의 admission gate를 그대로 적용한다.
3. 신규 worktree는 canonical path에서 exact base SHA의 detached HEAD로 생성하고 Issue 용도로 lock한다.
4. gitea-agent.worktree/v1 state를 canonical 방식으로 게시한다.
5. 기존 worktree는 state identity, Git registration, common directory, detached·locked 상태, base ancestry, dirty 상태와 미완료 Git operation을 모두 검증한 뒤 재사용한다.
6. 기존 worktree의 파일, untracked state 또는 commit을 reset, clean, rebase, checkout, switch 또는 삭제로 자동 복구하지 않는다.
7. Repository lock을 해제하고 Issue lock은 유지한다.

완료 조건: exact worktree path, base SHA, current HEAD, detached·locked 상태와 approval snapshot binding이 canonical 검증을 통과한다.

5. Repository baseline 조사

1. search_files, read_file과 worktree를 대상으로 한 read-only terminal Git 명령으로 tree, build 설정, test runner, formatter, lint와 기존 문서 구조를 조사한다.
2. Discovery가 언급한 모든 source와 test 경로를 실제 base에서 읽는다. 읽지 않은 파일을 근거로 구현을 설계하지 않는다.
3. Repository가 선언한 canonical install과 test 명령을 찾는다. 임의의 전역 package 설치나 운영 credential을 사용하지 않는다.
4. 관련 기존 test를 수정 전 실행하고 exit code와 실패 내용을 보존한다.
5. Baseline 실패가 변경 대상과 관련되거나 새 구현의 판정을 방해하면 수정하지 않고 blocker로 보고한다. 명백히 무관한 기존 실패라면 범위와 evidence를 기록하고 영향받는 test를 별도로 판정한다.

완료 조건: 변경 대상의 현재 동작, dependency direction, test command와 baseline 결과가 실제 output으로 확인됐다.

6. 요구 문서 작성

Discovery가 신규 작성 또는 수정으로 판정한 문서만 작성한다.

1. 요구사항명세서는 read_file로 harness의 요구사항 작성 방법과 요구사항 템플릿을 새로 읽고 Discovery가 지정한 target repository의 exact ID·경로로 작성한다.
2. 데이터 모델은 영향이 있을 때만 harness의 데이터 모델 작성 방법과 데이터 모델 템플릿을 적용한다.
3. 인터페이스 계약은 영향이 있을 때 harness의 인터페이스 계약 작성 방법과 인터페이스 계약 템플릿을 적용한다.
4. 프로젝트 구조는 영향이 있을 때 harness의 프로젝트 구조 작성 방법과 프로젝트 구조 템플릿을 적용한다.
5. 런타임 흐름은 영향이 있을 때 harness의 런타임 흐름 작성 방법과 런타임 흐름 템플릿을 적용한다.
6. Requirement frontmatter는 canonical gitea-agent.requirement/v1 계약을 만족하고 status를 approved로 기록한다. 구현 PR이 아직 없으면 미정을 유지하고 번호를 추측하지 않는다.
7. 모든 placeholder, 작성 안내 문구, 실제 credential과 확인되지 않은 경로를 제거한다.

완료 조건: Discovery의 문서 영향 판정과 생성·수정된 문서 집합이 정확히 일치하고 각 문서가 해당 README와 TEMPLATE 검증을 통과한다.

7. Test-first 구현

1. Acceptance matrix에서 변경 전 실패해야 하는 정상, 실패, 경계와 보안 test를 먼저 추가한다.
2. 새 test가 의도한 이유로 실패하는지 실행해 확인한다. 환경 오류나 잘못된 fixture 실패를 RED evidence로 사용하지 않는다.
3. 기존 architecture와 dependency direction을 유지하는 최소 source 변경으로 test를 통과시킨다.
4. 실패 경로가 외부 상태를 변경하지 않는지 검증한다.
5. 실제 운영 데이터, password, token 또는 credential을 test와 fixture에 사용하지 않는다.
6. Timing, concurrency 또는 retry 조건은 clock·sleep 의존성을 주입하거나 통제 가능한 seam으로 unit test하되, Discovery가 실제 elapsed-time 보장을 요구하면 실제 통합 경로 test도 유지한다.
7. 관련 test를 작은 단위로 반복한 뒤 전체 관련 suite를 실행한다.

완료 조건: 각 acceptance criterion에 실제로 실행된 test 또는 판정 가능한 문서·정적 검증 evidence가 연결돼 있다.

8. 통합 검증과 독립 검토

1. Repository가 요구하는 formatter, lint, type check, build와 test suite를 실제 실행한다.
2. Base-to-worktree diff를 읽고 모든 변경 파일을 acceptance matrix와 대응한다.
3. 범위 밖 변경, debug artifact, generated drift, credential material, query parameter secret, test-only bypass와 운영 데이터가 없는지 검사한다.
4. 새 dependency가 있다면 필요성과 lockfile·deployment 반영을 검증한다.
5. 설정 예시에는 secret 이름과 용도만 기록하고 실제 값을 넣지 않는다.
6. 독립 검토가 유용하면 delegate_task로 bounded reviewer를 사용한다. Reviewer에게 exact worktree path, base SHA, Issue snapshot, acceptance matrix와 검증 명령을 전달하고 Gitea write, Git cleanup, commit과 push를 금지한다.
7. Main agent가 reviewer 지적을 직접 재현하고 유효한 문제만 수정한 뒤 영향을 받은 검증을 다시 실행한다.

완료 조건: 모든 modified file이 승인된 산출물로 설명되고, 실행한 quality gate와 unresolved finding이 명확하다.

9. Drift 확인, commit과 PR 전달

1. Gitea Issue와 comments를 다시 읽어 approval snapshot의 body, updated_at과 comment baseline drift를 확인한다.
2. Repository lock 아래 origin을 다시 fetch하고 Gitea default branch SHA와 local ref를 확인한다.
3. Default branch가 base 이후 전진했으면 자동 merge, rebase 또는 history rewrite하지 않는다. 새 변경이 구현과 충돌하지 않는지 판정할 수 없으면 delivery-ready로 보고하지 않는다.
4. Worktree의 base SHA, final HEAD, staged·unstaged·untracked 상태, 미완료 Git operation과 test 결과를 기록한다.
5. Branch 이름은 repository convention이 있으면 이를 따르고, 없으면 gitea-agent/issue-<number>-<short-slug>처럼 deterministic Issue 전용 이름을 사용한다. Gitea와 remote에서 동일 이름의 branch와 열린 PR을 먼저 조회해 중복 생성하지 않는다.
6. 승인된 modified·untracked file을 exact allowlist로 stage하고 staged diff를 다시 읽는다. 범위 밖 파일, credential, generated artifact 또는 예상하지 못한 삭제가 있으면 commit하지 않는다.
7. Repository convention에 맞는 non-amended commit을 생성하고 base ancestry, commit tree와 worktree 상태를 검증한다.
8. Issue 전용 branch가 없으면 final commit을 가리키도록 생성하고, 있으면 현재 작업이 소유한 branch이며 fast-forward 가능한 경우에만 갱신한다. Default branch에는 직접 push하지 않고 force-push하지 않는다. Canonical cache의 mirror remote 설정을 변경하지 말고 push할 때 explicit repository URL과 refspec을 사용한다.
9. Target repository write 권한이 없으면 같은 push를 반복하지 않는다. Authenticated identity가 fork를 생성할 수 있으면 기존 fork·동명 branch·PR 유무와 fork parent/base SHA를 검증한 뒤 fork의 Issue 전용 branch로 non-force push하고 cross-repository PR을 사용한다. Fork도 쓸 수 없으면 permission blocker와 local commit SHA를 보고한다.
10. Remote readback으로 branch owner, repository, branch SHA가 local commit SHA와 exact-match하는지 확인한다.
11. Default branch를 base로 PR을 생성한다. 제목은 Issue를 식별하고, 본문에는 Closes #<number>, 구현 요약, 문서 변경, 실제 검증 명령·결과, 제한사항과 보안상 주의점을 기록한다. PR 생성 자체로 Issue state를 변경하지 않는다.
12. PR 번호를 얻은 뒤 요구사항 문서의 구현 PR: 미정을 실제 PR 번호 또는 URL로 교체하고, 문서 검증과 관련 test를 재실행해 별도 commit으로 같은 branch에 non-force push한다.
13. Gitea에서 PR details, base branch, head repository·branch·SHA, state, changed files와 commit을 다시 읽는다. 최종 remote head SHA가 최종 local commit SHA와 일치할 때만 전달 완료로 판정한다.
14. PR 생성 또는 후속 push가 부분 실패하면 blind retry하거나 중복 PR을 만들지 않는다. 이미 생성된 fork·branch·PR과 local commit의 exact 상태 및 안전한 복구 지점을 보고한다.

완료 조건: Issue와 source drift, final worktree 상태와 실행 결과가 fresh readback으로 확인되고, 열린 Gitea PR의 base·head와 remote head SHA가 검증된 최종 local commit에 exact-match한다.

위임 규칙

Main agent는 구현 범위와 최종 결과에 책임을 진다. 독립적인 repository 조사, test 작성, 특정 모듈 구현, 보안 검토 또는 실패 분석은 병렬 위임할 수 있지만 다음을 지킨다.

• Delegate에 Issue body 전체가 아니라 필요한 확정 계약, exact worktree path와 금지된 side effect를 명시한다.
• 같은 파일을 병렬로 수정하는 worker를 만들지 않는다.
• Delegate가 Gitea write, lock 변경, worktree 생성·제거, commit, push 또는 reset을 수행하지 못하게 한다.
• Delegate의 성공 주장을 evidence로 간주하지 않고 main agent가 diff와 test output을 직접 확인한다.
• 외부 side effect는 main agent만 수행하고 즉시 authoritative readback한다.

주의점과 금지 사항

• 미해결 질문이나 충돌하는 결정을 임의로 선택하지 않는다.
• Issue body에 없는 기능, migration, refactor 또는 dependency를 편의상 추가하지 않는다.
• Moving branch나 stale cache를 구현 근거로 사용하지 않는다.
• Bare mirror에 구현용 local branch를 만들지 않는다.
• 다른 worktree의 변경을 가져오거나 정리하지 않는다.
• 기존 dirty state를 reset, clean, stash, checkout 또는 force remove하지 않는다.
• test를 통과시키기 위해 production security gate, validation 또는 실패 경로를 약화하지 않는다.
• 실제 credential, 운영 DB 또는 사용자 금융 데이터를 test나 artifact에 사용하지 않는다.
• 실행하지 않은 test, 읽지 않은 파일 또는 확인하지 않은 Gitea 상태를 성공 evidence로 보고하지 않는다.
• Issue 구현 요청 범위를 벗어난 commit·push·PR 변경, force-push, merge, Issue 변경, release 또는 deployment를 수행하지 않는다.
• 실패하거나 불확실한 외부 write를 blind retry하지 않는다.

검증 및 보고

완료 보고에는 다음을 구분해 포함한다.

• authenticated Gitea identity와 exact target
• approval snapshot의 Issue updated_at, body digest와 미해결 질문 검증
• cache path, bare·remote 검증, fetch 결과와 Gitea/local SHA
• Discovery pinned SHA, selected base SHA와 차이 판정
• worktree path, 신규 생성 또는 재사용, detached·locked 상태와 final HEAD
• 요구 문서별 조치, exact path와 canonical template 검증
• acceptance criterion별 구현 위치와 test evidence
• baseline, targeted와 full-suite 명령의 실제 exit 결과
• modified file 전체와 범위 내 변경 근거
• staged, unstaged, untracked, 미완료 Git operation, local commit과 remote branch SHA
• Issue와 default branch의 최종 drift readback
• PR 번호·URL·base·head·state와 PR head SHA readback
• 수행한 commit·push·PR write와 수행하지 않은 merge·Issue·release write
• blocker, 기존 실패, unresolved risk 또는 partial 상태

파일 작성, process exit, test 일부 통과, local commit 또는 delegate 보고만으로 완료를 주장하지 않는다. 모든 승인된 산출물이 worktree에 존재하고 acceptance matrix, 실제 test output, final diff, remote branch와 열린 PR의 fresh Gitea readback이 일치할 때만 구현 완료로 판정한다.