Evo Workflow Template

workflow 표준을 새 GitLab 프로젝트에 설치하는 템플릿입니다. 저장소를 복사하지 않고 install.sh 한 줄로 설치하며, 프로젝트마다 달라지는 값(프로젝트 이름, GitLab 경로)만 채워집니다. 프로젝트 이름은 표준 이름 규칙에 따라 workflow-project-<이름>으로 정해집니다.

• 설치에는 sh, curl, tar만 필요합니다. Python은 필요 없습니다.
• 업데이트(update)에는 3-way 병합을 위해 git이 추가로 필요합니다.

설치하면 만들어지는 것

workflow 표준은 AI 에이전트가 코드·Issue·MR·CI·검증 작업을 일관되고 감사 가능한 방식으로 수행하도록 정한 규칙 모음입니다. 설치하면 프로젝트 폴더에 다음이 생깁니다.

경로	내용
AGENTS.md	에이전트 진입점. 작업 라우팅, 보안·검증 규칙, Human 승인 경계
README.md, docs/README.md	프로젝트 안내와 공식 문서 진입점 (프로젝트 이름이 채워짐)
.agent-workflow/project-overlay.yaml	프로젝트 설정: GitLab 경로, Profile, 검증 명령
.agent-workflow/standards/	운영 표준 25종 (Issue 작성·분류·계약, 변경 게시, 독립 검증, Evidence 관리, 이름 규칙 등)
.agent-workflow/profiles/, registry/	작업 유형별 Workflow Profile 7종 (issue-only, issue-intake, coding-task, review-only, pr-rework, ci-failure-recovery, evidence-approval)과 등록부
.agent-workflow/schemas/, scripts/	Issue Contract 스키마와 검증 스크립트

| .gitlab/ | Issue 템플릿 3종, MR 템플릿 | | .gitlab-ci.yml | 지침 정합성 검증과 테스트를 실행하는 CI | | .workflow.yml | 설치 기록(템플릿 버전, 프로젝트 이름, GitLab 경로·URL). 업데이트에 필요하므로 함께 커밋합니다 |

설치

프로젝트 이름(폴더)은 표준 이름 규칙에 따라 workflow-project-<이름> 으로 정해집니다. 사용자는 뒤에 붙을 이름(표준 용어로 project-id)만 입력합니다.

입력한 이름	만들어지는 프로젝트(폴더)
stock-trader	workflow-project-stock-trader
sample	workflow-project-sample

대화형 설치 (옵션 없이)

curl -fsSL https://nexus.bluewindsky.com/repository/evo-bin/workflow/v1/install.sh | sh

차례로 묻고, 마지막에 설치할 내용을 보여 준 뒤 확인을 받습니다.

설치 위치 (비우면 현재 폴더) [/home/me/work]:
프로젝트 이름 (workflow-project- 뒤에 붙습니다, lowercase kebab-case): stock-trader
  → workflow-project-stock-trader
GitLab 프로젝트 URL 또는 <GROUP>/<PROJECT> (비우면 나중에 설정): https://git.bluewindsky.com/framework/evomind/workflow-project-stock-trader.git

  템플릿 버전    : 1.0.4
  설치 경로      : /home/me/work/workflow-project-stock-trader
  프로젝트 이름  : workflow-project-stock-trader
  GitLab         : https://git.bluewindsky.com/framework/evomind/workflow-project-stock-trader.git
이대로 설치할까요? (Y/n):

• 설치 위치: 프로젝트 폴더를 만들 상위 폴더입니다. 비우면 현재 폴더이고, ~/…도 쓸 수 있습니다. 없는 폴더면 새로 만듭니다.
• 프로젝트 이름: workflow-project- 뒤에 붙을 이름입니다. lowercase 영문·숫자·하이픈만 쓸 수 있고, 설치 위치에 같은 이름의 폴더가 있으면 다른 이름을 묻습니다.
• GitLab 프로젝트: 전체 URL(https://host/<GROUP>/<PROJECT>.git) 또는 <GROUP>/<PROJECT>를 입력합니다. .agent-workflow/project-overlay.yaml의 project_id에는 <GROUP>/<PROJECT>가, 설치 기록(.workflow.yml)에는 URL까지 저장됩니다. 아직 GitLab 프로젝트가 없으면 비워 두고 나중에 config로 등록합니다.

잘못된 값을 입력하면 이유를 보여 주고 다시 묻습니다. 확인 질문에 n을 입력하면 아무것도 만들지 않고 끝납니다.

설치가 끝나면 프로젝트 폴더는 git 저장소로 초기화되고(git init, 기본 브랜치 main), GitLab을 전체 URL로 입력했다면 origin remote까지 연결됩니다. 커밋은 하지 않으므로 내용을 확인한 뒤 직접 커밋·푸시합니다.

cd workflow-project-stock-trader
git add -A && git commit -m "Install workflow template"
git push -u origin main

옵션으로 설치

옵션은 sh -s -- 뒤에 붙입니다. 옵션으로 준 값은 묻지 않고, 빠진 값만 묻습니다.

# 모든 값을 지정 — 질문 없이 설치
curl -fsSL https://nexus.bluewindsky.com/repository/evo-bin/workflow/v1/install.sh | sh -s -- \
  --location ~/work --name stock-trader \
  --gitlab-path https://git.bluewindsky.com/framework/evomind/workflow-project-stock-trader.git

# 이름만 지정 — 설치 위치와 GitLab 경로는 묻는다
curl -fsSL https://nexus.bluewindsky.com/repository/evo-bin/workflow/v1/install.sh | sh -s -- --name stock-trader

# --yes — 묻지 않고 기본값으로 설치 (현재 폴더, GitLab은 비워 두고 나중에 등록)
curl -fsSL https://nexus.bluewindsky.com/repository/evo-bin/workflow/v1/install.sh | sh -s -- --yes --name stock-trader

옵션	의미	지정하지 않으면
--location <path>	설치 위치(프로젝트 폴더를 만들 상위 폴더)	묻는다 (비우면 현재 폴더)
--name <name>	workflow-project- 뒤에 붙을 프로젝트 이름. lowercase 영문·숫자·하이픈. --project-id도 같은 뜻	묻는다
--gitlab-path <url|path>	GitLab 프로젝트 URL 또는 <GROUP>/<PROJECT> (별칭 --gitlab-url)	묻는다 (비우면 나중에 config로 등록)
--version <ver>	설치할 템플릿 버전 (예: 1.0.4)	v1 최신 버전
--yes, -y	아무것도 묻지 않고 기본값으로 설치	빠진 값은 묻고, 질문한 경우 마지막에 확인
--help, -h	사용법 출력	—

--yes일 때 빠진 값은 다음 기본값을 씁니다.

값	--yes 기본값
설치 위치	현재 폴더
프로젝트 이름	기본값이 없으므로 --name을 반드시 지정 (없으면 오류)
GitLab	비움 (나중에 config로 등록)

환경 변수 WORKFLOW_GITLAB_GROUP을 지정하면 GitLab 기본값을 <그룹>/workflow-project-<name>으로 채웁니다.

curl -fsSL .../workflow/v1/install.sh | WORKFLOW_GITLAB_GROUP=framework/evomind sh -s -- --yes --name portal

터미널이 없는 환경(CI 등)에서는 질문할 수 없으므로, 설치 위치는 현재 폴더를 쓰고 GitLab은 비워 두며 --name은 반드시 지정해야 합니다.

설치 폴더에 같은 이름의 폴더가 이미 있으면 아무것도 쓰지 않고 중단합니다.

GitLab 프로젝트 나중에 등록 (config)

설치할 때 GitLab을 비워 두었거나 바꿔야 하면, GitLab 프로젝트를 만든 뒤 프로젝트 폴더에서 config를 실행합니다. GitLab 주소를 물어보고, 입력하면 설정 파일 갱신과 origin remote 연결까지 자동으로 합니다.

cd workflow-project-stock-trader
curl -fsSL https://nexus.bluewindsky.com/repository/evo-bin/workflow/v1/install.sh | sh -s -- config

현재 GitLab: (비어 있음)
GitLab 프로젝트 URL (https://host/<GROUP>/<PROJECT>.git): https://git.bluewindsky.com/framework/evomind/workflow-project-stock-trader.git
GitLab 설정: https://git.bluewindsky.com/framework/evomind/workflow-project-stock-trader.git (project_id: framework/evomind/workflow-project-stock-trader)
  git remote origin 연결: https://git.bluewindsky.com/framework/evomind/workflow-project-stock-trader.git

• origin이 이미 연결돼 있으면 그 주소를 기본값으로 보여 주므로 엔터만 누르면 됩니다.
• 잘못된 값이나 빈 값을 입력하면 다시 묻습니다.
• 질문 없이 하려면 주소를 옵션으로 줍니다: ... | sh -s -- config --gitlab-path <URL>
• 터미널이 없는 환경(CI 등)에서는 origin을 읽고, 없으면 --gitlab-path를 지정해야 합니다.

등록한 뒤 커밋·푸시합니다.

git add -A && git commit -m "Set GitLab project"
git push -u origin main

옵션	의미	지정하지 않으면
--dir <path>	프로젝트 폴더	현재 폴더
--gitlab-path <url|path>	등록할 GitLab URL 또는 <GROUP>/<PROJECT>	묻는다 (origin이 있으면 기본값으로 제안)

config가 하는 일:

대상	처리
.agent-workflow/project-overlay.yaml	project_id를 <GROUP>/<PROJECT>로 설정
.workflow.yml	gitlab_path, gitlab_url 기록
git origin remote	전체 URL이면 연결 (없으면 추가). 이미 다른 주소가 연결돼 있으면 덮어쓰지 않고 안내

URL에 인증 정보(https://user:token@…)가 들어 있어도 출력·파일·remote에는 인증 정보를 뗀 주소만 남깁니다. 푸시 인증은 git credential helper나 glab 로그인을 사용합니다.

GitLab이 비어 있는 동안 에이전트는 Issue·MR 작성 같은 GitLab 쓰기 작업 전에 이를 확인하고, 추측하지 않고 멈춰서 등록을 요청합니다(AGENTS.md의 “GitLab 대상 프로젝트 확인”). 로컬 코드 수정이나 검증은 영향받지 않습니다.

업데이트

템플릿의 새 버전을 설치된 프로젝트에 3-way 병합으로 반영합니다. 프로젝트 이름과 GitLab 경로는 .workflow.yml에서 읽으므로 다시 묻지 않습니다.

# 프로젝트 폴더 안에서
curl -fsSL https://nexus.bluewindsky.com/repository/evo-bin/workflow/v1/install.sh | sh -s -- update

# 다른 위치에서 프로젝트 폴더 지정
curl -fsSL https://nexus.bluewindsky.com/repository/evo-bin/workflow/v1/install.sh | sh -s -- update --dir ~/work/workflow-project-stock-trader

옵션	의미	지정하지 않으면
--dir <path>	업데이트할 프로젝트 폴더	현재 폴더
--version <ver>	반영할 템플릿 버전	v1 최신 버전

파일 상태	처리
프로젝트에서 수정하지 않은 파일	새 버전으로 교체
프로젝트와 템플릿이 모두 수정한 파일	병합. 같은 위치를 수정했으면 <<<<<<< 충돌 표시를 남기고 종료 코드 2
템플릿에 새로 생긴 파일	추가 (같은 이름의 다른 파일이 있으면 <파일>.workflow-new로 저장)
템플릿에서 삭제된 파일	프로젝트에서 수정하지 않았을 때만 삭제

결과를 git diff로 확인하고, 충돌이 있으면 해결한 뒤 .workflow.yml과 함께 커밋합니다.

템플릿 저장소 구성

template/              설치되는 내용. *.tmpl 파일은 설치 시 변수가 치환되고 확장자가 제거된다
install.sh             설치·업데이트 스크립트 (Nexus에 배포)
scripts/build-dist.sh  배포 산출물 생성
.gitlab-ci.yml         설치 테스트 + tag 배포

.tmpl 파일에서 사용하는 변수:

변수	값
{{project_name}}	프로젝트 이름 (예: workflow-project-stock-trader)
{{gitlab_path}}	GitLab 프로젝트 경로 <GROUP>/<PROJECT>, 비워 두면 빈 값 (이전 표기 {{project_id}}도 같은 값으로 치환)
{{PROJECT_NAME_UPPER}}	프로젝트 이름의 대문자·밑줄 형식 (예: WORKFLOW_PROJECT_STOCK_TRADER)

배포

main에 push하면 CI가 템플릿을 빌드해 실제로 설치하고, 설치된 프로젝트의 검증 명령을 실행합니다. 배포는 버전 tag로 합니다.

git tag v1.0.3 && git push origin v1.0.3

tag 파이프라인이 Nexus evo-bin/workflow/v<major>/에 다음을 올립니다(latest는 마지막에 갱신).

evo-bin/workflow/v1/install.sh
evo-bin/workflow/v1/latest
evo-bin/workflow/v1/<ver>/workflow-template-gitlab-<ver>.tar.gz
evo-bin/workflow/v1/<ver>/sha256sums.txt

자동 배포에는 프로젝트 CI/CD 변수 NEXUS_USER, NEXUS_PASSWORD가 필요합니다. 변수가 없으면 배포 job은 실행되지 않습니다.

로컬에서 산출물만 만들 때:

sh scripts/build-dist.sh 1.0.3   # dist/ 에 생성