aidlc-using-devflow

name	aidlc-using-devflow
description	AIDLC 워크플로우로 새 프로젝트를 시작하거나, 기존 devflow 세션을 재개하거나, "devflow 시작" 또는 "devflow 재개" 요청 시 사용. Use when starting a new project with AIDLC workflow, resuming an existing devflow session, or when "devflow 시작" or "devflow 재개" is requested.
metadata	{"version":"0.6.0","author":"Jay","category":"ai-dlc-workflow","invoke_mode":"user-invocable","return_behavior":"stop-with-gate","skill_nature":"amplification","lifecycle":"active"}

aidlc-using-devflow

Trigger

사용자가 아래 중 하나를 요청하면 이 워크플로우를 시작한다:

• 새 기능 개발, 버그 수정, 리팩토링 등 구현 작업
• "devflow", "aidlc", "워크플로우" 언급
• 코드 변경이 필요한 모든 요청

On Activation

Step 1: 기존 세션 확인

devflow-docs/devflow-state.md가 존재하는지 확인한다.

존재하지 않으면 → New Flow 존재하면 → Resume Flow

New Flow

1. 환영 메시지 표시:

   ## aidlc 워크플로우 시작
   
   AI-DLC 기반 개발 워크플로우가 활성화되었습니다.
   
   진행 단계:
   🔵 INCEPTION  → 무엇을 만들지 결정
   🟢 CONSTRUCTION → 어떻게 만들지 결정
   

2. 기존 산출물 확인 게이트: devflow-docs/inception/ 디렉토리에 산출물(.md 파일, workspace.md 제외)이 존재하는지 확인한다. 또한 devflow-docs/.archive/ 내 이전 세션 수를 카운트한다 (inception-* 디렉토리 수).

   산출물이 없는 경우:

   • .archive/에 이전 세션이 있으면 이력 안내 후 Step 3으로 진행:

     (현재 inception/ 산출물 없음)
     이전 아카이브: [N]개 세션 (.archive/에서 참조 가능)
     
     → 새 작업을 시작합니다.
     

   • .archive/도 없으면 안내 없이 Step 3으로 진행 (정상 새 시작)

   (선택) 운영 패턴 채택 안내 — 첫 진입(.archive/도 없는 정상 새 시작) 시 한 번 표시:

   💡 운영 패턴 템플릿 (선택)
   
   plugin의 `docs/guide/memory-templates.md`에 mid-cycle stop / 세션 종료 응답 형식 등
   채택 가능한 운영 패턴이 있습니다. 본인 프로젝트 환경에 맞으면 자연 발화로 채택:
     "memory-templates.md에서 [패턴명]을 내 프로젝트 메모리에 복사해줘"
   
   강제 안 함. 무시하고 진행해도 됩니다.
   

   본 안내는 신규 프로젝트 첫 진입 시 1회만 권장. 이미 auto-memory에 운영 패턴이 있거나 사용자가 원하지 않는 신호 시 생략.

   산출물이 있는 경우 → requirements.md에서 ## User Intent 내용과 **Depth** 값, **Timestamp** 값을 읽어 기존 산출물 처리 게이트를 제시한다. requirements.md가 없거나 해당 섹션이 비어 있으면 "(정보 없음)"으로 대체한다:

   ## 기존 INCEPTION 산출물 발견
   
   이전 작업: "[User Intent 1줄 요약]" ([Timestamp 날짜], [Depth])
   산출물: [파일 목록] ([N]개)
   이전 아카이브: [N]개 세션 (.archive/에서 참조 가능)
   
   A) 기존 설계 기반으로 보완 (UPDATE 모드)
      → 이전 요구사항/설계를 유지하고 새 기능을 추가합니다
   B) 처음부터 새로 시작 (기존 산출물 아카이브)
      → 기존 inception/, construction/ 을 .archive/로 이동 후 새로 시작합니다
      ※ workspace.md는 유지됩니다
      ※ 이전 산출물은 .archive/에서 언제든 참조 가능합니다
   

   A 선택 시:

   • devflow-audit에 로깅: "New flow — UPDATE mode (preserving existing artifacts)"
   • 이후 inception-orchestrator에서 호출하는 각 스테이지 스킬이 기존 파일을 감지하면 UPDATE 모드로 동작

   B 선택 시:

   • devflow-docs/inception/workspace.md가 있으면 임시로 보존 (이동 전 별도 보관)
   • devflow-docs/inception/을 devflow-docs/.archive/inception-[timestamp]/로 이동
   • devflow-docs/construction/을 devflow-docs/.archive/construction-[timestamp]/로 이동 (있으면)
   • 보존한 workspace.md를 새로 생성된 devflow-docs/inception/workspace.md로 복원
   • devflow-audit에 로깅: "New flow — clean start (artifacts archived, workspace.md preserved)"

3. devflow-docs/ 디렉토리 생성 (하위 inception/, construction/ 포함 — 이미 있으면 유지)

4. devflow-docs/devflow-state.md 초기화:

   # DevFlow State
   
   ## Current Phase
   INCEPTION
   
   ## Current Stage
   (pending)
   
   ## Complexity
   (pending)
   
   ## Selected Approach
   (pending)
   

5. 백로그 확인 (Lazy Loading): devflow-docs/backlog.md가 존재하면:

   • ## Next, ## Open 섹션의 항목 수(- **BL- 패턴)만 카운트한다. 파일 내용은 로드하지 않는다.
   • 안내 표시:

     백로그: Next [N]건, Open [M]건
     → 백로그를 확인하려면 "백로그 보여줘"라고 요청하세요.
     

   • 사용자가 요청하지 않으면 내용을 로드하지 않고 다음 단계로 진행한다.
   • 파일이 없으면 이 단계를 건너뛴다.

6. devflow-audit에 로깅: "New aidlc session started" + 사용자 원래 요청

7. aidlc-inception-orchestrator 호출

Resume Flow

1. devflow-docs/devflow-state.md 읽기

2. devflow-docs/session-summary.md 읽기 (있으면)

   Memory Sync Staleness Check (optional, auto-memory 운영 시):

   • Preflight — upstream 확인: git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null
     • 성공 → ahead check 진행
     • 실패 → "upstream 미설정 — staleness check 비활성. 필요 시 git push -u origin HEAD로 upstream 설정" 안내 + devflow-docs/audit.md에 한 줄 기록 후 이 step 종료: [<ISO timestamp>] memory-sync-staleness-skipped | branch=<name> | ahead=0 | reason=upstream-unset
   • Ahead check: git rev-list --count @{upstream}..HEAD. 1 이상이면 아래 프롬프트: "⚠️ push 보류 감지 — local ahead J commits. A) 갱신 후 Resume / B) 그대로 Resume"
   • A 선택 시 권장 절차 (강제 아님, advisory): (1) git push 실행 → (2) 성공 시 git rev-list --count @{upstream}..HEAD 재확인하여 ahead==0이면 Resume 진행. sync 실패 시 에러 표시 + Resume 보류 권고(최종 판단은 사용자).
   • 실행 기록 (preflight 통과 시 항상) — devflow-docs/audit.md에 한 줄 append: [<ISO timestamp>] memory-sync-staleness-check-run | branch=<name> | ahead=<N> | prompted=<true|false>
   • B 선택 시 추가 기록: [<ISO timestamp>] memory-sync-staleness-skipped | branch=<name> | ahead=<N> | reason=<optional>
   • upstream 미설정 또는 ahead 0이면 프롬프트는 no-op

3. 백로그 확인 (Lazy Loading): devflow-docs/backlog.md가 존재하면:

   • ## Next, ## Open 섹션의 항목 수(- **BL- 패턴)만 카운트한다. 파일 내용은 로드하지 않는다.
   • 안내 표시:

     백로그: Next [N]건, Open [M]건
     → 백로그를 확인하려면 "백로그 보여줘"라고 요청하세요.
     

   • 사용자가 요청하지 않으면 내용을 로드하지 않고 다음 단계로 진행한다.
   • 파일이 없으면 이 단계를 건너뛴다.

4. ## Current Phase 값에 따라 분기:

상태 디스패치 테이블

Phase 값	조건	동작	게이트
finished	—	아카이브 → New Flow	없음 (자동)
complete	Finishing == "B (PR pending)"	PR 자동 확인 → 게이트	A/B
complete	Finishing 없음	—	A/B
INCEPTION	—	—	A/B
CONSTRUCTION	—	—	A/B
파싱 불가	—	백업 → New Flow	없음 (자동)

자동 처리 경로

finished: state와 session-summary(있으면)를 devflow-docs/.archive/로 이동 후 New Flow 진행. 사용자 안내 없음.

파싱 불가: devflow-docs/.archive/devflow-state-backup-[timestamp].md로 백업 후 New Flow 진행.

게이트 경로

complete + PR pending

gh pr view [PR URL] --json state로 PR 상태를 자동 확인한 뒤 게이트를 제시한다.

PR 이미 머지된 경우:

## aidlc — PR 머지 확인됨

PR [URL]이 머지되었습니다.

A) devflow 종료 처리 → 아카이브 + 워크트리 정리 + New Flow
B) 새 작업 시작 (아카이브만)

PR 아직 열린 경우:

## aidlc — PR 대기 중

PR [URL]이 아직 열려있습니다.

A) devflow 종료 처리 (PR 머지 완료로 간주)
B) 다른 작업 시작 (아카이브)

A 선택 시:

• devflow-state의 ## Current Phase를 finished로 업데이트
• state와 session-summary를 .archive/로 이동
• 워크트리 존재 시 제거 (git worktree remove + git worktree prune)
• devflow-audit에 로깅: "Flow finished — PR merged"

B 선택 시:

• state와 session-summary를 .archive/로 이동
• New Flow 진행

complete (Finishing Choice 없음)

## aidlc — CONSTRUCTION 완료, 브랜치 처리 대기

A) aidlc-finishing-a-development-branch 실행 → 브랜치 처리
B) 새 작업 시작 (기존 상태 초기화)

INCEPTION 또는 CONSTRUCTION

## aidlc — 진행 중인 작업 발견

현재 단계: [Current Phase] > [Current Stage]
완료된 스테이지: [list]

A) 이전 작업 재개
B) 새 작업 시작 (기존 상태 초기화)

A 선택 시:

• devflow-audit에 로깅: "Session resumed at [stage] — commit: [git rev-parse --short HEAD]"
• 해당 Phase Orchestrator 호출

B 선택 시:

• state와 session-summary를 .archive/로 이동
• New Flow 진행

Phase 전환

INCEPTION 완료 시

aidlc-inception-orchestrator가 INCEPTION 완료를 반환하면:

1. devflow-state의 ## Current Phase를 CONSTRUCTION으로 업데이트
2. devflow-docs/session-summary.md 업데이트:
   • ## Current State의 Phase를 CONSTRUCTION으로
   • **Commit** 필드에 현재 HEAD hash
   • devflow-audit에 "Phase transition: INCEPTION → CONSTRUCTION — commit: [hash]"
3. aidlc-construction-orchestrator 호출

CONSTRUCTION 완료 시

aidlc-construction-orchestrator가 CONSTRUCTION 완료를 반환하면:

1. devflow-state의 ## Current Phase를 complete로 업데이트
2. devflow-docs/session-summary.md 최종 업데이트:
   • ## Current State의 Phase를 complete로
   • **Commit** 필드에 현재 HEAD hash
   • ## Next Steps에 "aidlc-finishing-a-development-branch로 머지/PR 진행"
3. devflow-audit에 로깅: "Construction complete — commit: [hash]"
4. 완료 안내:

   🎉 INCEPTION + CONSTRUCTION 완료
   
   산출물:
   - devflow-docs/inception/ (요구사항, 설계, 워크플로우 계획)
   - devflow-docs/construction/ (코드 계획, 빌드/테스트 지침)
   
   다음 단계:
   → aidlc-finishing-a-development-branch로 머지/PR 진행
   

Auxiliary Skill 라우팅

CONSTRUCTION 도중 사용자가 아래 상황을 보고하면 해당 스킬로 안내한다:

버그/테스트 실패 시

aidlc-systematic-debugging 스킬을 호출하도록 안내한다. 근본 원인 파악 없이 즉흥적으로 코드를 수정하지 않는다.

완료 주장 시

aidlc-verification-before-completion 스킬을 호출하여 실제 명령 실행 결과로 완료를 검증한다.

개발 브랜치 완료 후

aidlc-finishing-a-development-branch 스킬을 호출하여 병합/PR/유지/폐기 선택지를 제시한다.

설계/계획 요청 시

• 설계 협업 요청 → aidlc-brainstorming 안내
• 구현 계획 작성 요청 → aidlc-writing-plans 안내
• 구현 계획 실행 요청 → aidlc-subagent-driven-development 안내
• TDD 강제 필요 시 → aidlc-test-driven-development 참조

Error Handling

devflow-docs/ directory missing

devflow-docs/가 없으면 디렉토리를 생성하고 새 세션으로 시작한다.

Stage artifact missing at resume

재개 시 기대하는 산출물이 없으면:

1. "⚠️ [stage-name] 산출물을 찾을 수 없습니다: [file-path]" 표시
2. A) 이전 단계부터 재실행 / B) 현재 단계 그대로 진행

devflow-state.md 손상

상태 파일 파싱 불가 시:

1. devflow-docs/.archive/devflow-state-backup-[timestamp].md로 백업
2. 새 세션 시작 (기존 산출물은 그대로 활용)

Stage skill 호출 실패

스킬이 예상치 못한 결과를 반환하면: A) 해당 단계 재시도 / B) 단계 스킵 (devflow-state에 skipped 기록)

Archive Convention

모든 아카이브 파일은 devflow-docs/.archive/에 저장한다. 디렉토리가 없으면 첫 아카이브 시 생성한다.

아카이브 대상 및 경로

대상	아카이브 경로
devflow-state.md	.archive/devflow-state-[timestamp].md
session-summary.md	.archive/session-summary-[timestamp].md
devflow-state.md (손상 백업)	.archive/devflow-state-backup-[timestamp].md
inception/ (B: 새로 시작)	.archive/inception-[timestamp]/ (workspace.md 제외 — 복원)
construction/ (B: 새로 시작)	.archive/construction-[timestamp]/

아카이브 일관성 규칙

state와 session-summary는 항상 함께 아카이브한다. 어떤 경로로 아카이브가 발생하든 두 파일 모두 이동한다 (session-summary가 없으면 state만).

아카이브 참조 정책

.archive/는 이전 산출물의 참조 저장소이다. 사용자 요청 또는 컨텍스트상 필요할 때 (예: 이전 기능의 요구사항 참고, NFR 재활용 등) 언제든 탐색·참조할 수 있다.