deuk-agent-flow 4.0.19

package/README.ko.md

@@ -0,0 +1,282 @@
+<div align="center">
+  <br />
+  <img src="docs/assets/architecture-v3.png" width="800" alt="DeukAgentFlow Architecture" />
+  <br />
+  <h1>Deuk Agent Flow v4.0.0</h1>
+  <p>
+    <a href="https://www.npmjs.com/package/deuk-agent-flow"><img src="https://img.shields.io/npm/v/deuk-agent-flow.svg?label=deuk-flow" alt="deuk-flow npm version" /></a>
+  </p>
+  <p><b>AI 코딩 작업이 대화창 밖으로 흘러내리지 않게.</b></p>
+  <p><i>"다음", "진행", "정리"처럼 짧게 말해도 티켓, 범위, 검증, 기억이 레포에 붙어 있게 만듭니다.</i></p>
+  <p><a href="https://deukpack.app">Deuk Family</a> 생태계의 핵심 모듈입니다.</p>
+  <p><a href="README.md">English</a> · <a href="README.ko.md">한국어</a></p>
+</div>
+
+---
+
+**Deuk Agent Flow**는 AI 코딩 에이전트를 위한 레포 소유 워크플로우 계층입니다. Codex, Copilot, Cursor, Claude Code, Gemini, Windsurf, 그리고 다음에 쓰게 될 에이전트까지 같은 티켓 흐름으로 들어오게 만듭니다.
+
+대부분의 에이전트 설정은 "지침"에서 멈춥니다. Deuk Agent Flow는 짧은 대화를 작업 루프로 바꿉니다: 티켓, 범위, 실행, 검증, 보관. 긴 명령을 외우지 않아도 `AGENTS.md`, Copilot instructions, Cursor rules, Claude skills 같은 표면을 같은 흐름으로 묶습니다.
+
+후킹 포인트는 단순합니다. 사용자가 "다음", "원인", "정리"라고만 해도 현재 에이전트가 그 의미를 붙잡을 레포 소유의 장소가 생깁니다. 진행 중인 작업은 `.deuk-agent/tickets/`에, 결정과 계획과 완료 근거는 코드베이스 옆에 남습니다. **Deuk Agent Flow**는 워크플로우 계층입니다. 이 흐름 전체에 별도 companion 제품인 **Deuk AgentContext**를 꽂으면 레포 전체가 확장된 프로젝트 브레인을 얻습니다. 검색 가능한 기억, 재사용되는 결정, 다음 에이전트가 실제로 쓰는 팀 패턴까지 붙습니다.
+
+### 왜 지금인가
+
+AI 코딩은 이미 장난감 단계를 넘어 production volume으로 들어갔습니다.
+
+- Google은 **새 코드의 75%가 AI 생성**이라고 밝혔습니다. 2024년 25%, 작년 가을 50%에서 빠르게 올라간 흐름입니다. ([Semafor, 2026](https://www.semafor.com/article/04/24/2026/google-ceo-says-75-of-companys-new-code-is-ai-generated))
+- Sonar의 2026 개발자 설문 보도에 따르면 현재 AI 생성 코드는 약 **42%**, 2027년에는 약 **65%**까지 오를 것으로 예상됩니다. ([TechRadar, 2026](https://www.techradar.com/pro/devs-dont-trust-ai-code-but-many-say-they-still-dont-check-it-anyways))
+- Stack Overflow 2025 설문 보도에서는 개발자 **84%**가 AI 도구를 쓰거나 쓸 계획이지만, "거의 맞지만 틀린 답"과 AI 코드 디버깅이 핵심 불만으로 꼽혔습니다. ([InfoWorld, 2025](https://www.infoworld.com/article/4031673/ai-use-among-software-developers-grows-but-trust-remains-an-issue-stack-overflow-survey.html))
+- Faros는 AI 도입 뒤 작업량은 늘었지만, **개발자당 버그 54% 증가**, 리뷰 시간 5배 증가, PR 대비 incident 증가라는 불편한 결과를 보고했습니다. ([ADTmag, 2026](https://adtmag.com/articles/2026/04/22/more-code-more-bugs.aspx))
+
+이제 병목은 코드를 더 빨리 쓰는 능력이 아닙니다. 에이전트 작업을 범위 안에 붙잡고, 리뷰 가능하게 만들고, 검증하고, 다음 세션에서도 이어받게 만드는 능력입니다.
+
+### 그래서 뭐가 달라지나
+
+| 없을 때 | Deuk Agent Flow 사용 시 |
+|---|---|
+| "다음"이 대화 기억에 의존 | "다음"이 레포 티켓으로 이어짐 |
+| 에이전트가 요청 밖까지 수정 | APC 범위가 수정 가능 경계를 잡음 |
+| 리뷰어는 코드만 보고 의도를 추측 | 티켓에 원인, 계획, 근거가 같이 남음 |
+| AI 출력이 리뷰 부담을 키움 | 검증과 closeout이 작업 루프에 포함됨 |
+| 대화가 끝나면 맥락도 사라짐 | archive와 지식 증류로 프로젝트 기억이 남음 |
+
+### 1분 시각화
+
+```text
+짧은 대화
+  "다음" / "원인" / "정리"
+        |
+        v
+Deuk Agent Flow
+  티켓 + 범위 + 검증 + 기억
+        |
+        v
+레포에 남는 작업
+  리뷰 가능한 변경 + 결정 근거 + 다음 세션 연결
+```
+
+| 장점 | 체감 |
+|---|---|
+| 맥락 손실 감소 | 다음 에이전트가 대화 전체를 다시 안 물어도 이어감 |
+| 범위 이탈 감소 | 티켓이 바꿔도 되는 것과 안 되는 것을 잡음 |
+| 리뷰 추측 감소 | diff 옆에 의도와 근거가 같이 남음 |
+| generated 코드 위험 감소 | 수정 전에 source/generator 소유자를 확인 |
+| 팀 기억 강화 | 완료된 작업이 검색 가능한 프로젝트 히스토리가 됨 |
+
+> **현재 배포 기준:**
+> v4.0.0은 에이전트 기반 리포지토리에 배포해 사용할 수 있는 상태입니다. 현재는 **OpenAI Codex**와 **GitHub Copilot** 환경에서 가장 안정적으로 동작합니다. Cursor, Windsurf, Claude Code, MCP도 포인터 구조로 지원하지만, 워크스페이스별 검증을 권장합니다. MCP 서버 등록은 `init`에 딸려 들어가지 않고 별도로 설정합니다.
+> **아키텍처 기반:**
+> 거대하고 무거운 레거시 `.cursorrules` 방식을 공식적으로 폐기했습니다. v3.0은 `AGENTS.md`를 단일 진실 공급원으로 사용하는 **Hub-Spoke 모델**을 도입하여, IDE별 규칙은 얇은 진입점 포인터 역할만 수행합니다.
+
+### 🗺️ 핵심 기능 및 아키텍처 (Main Features)
+
+Deuk Agent Flow는 AI 에이전트가 코드를 분석하고 작성하는 흐름을 안정적으로 이끄는 **4대 핵심 기능**을 제공합니다.
+
+1. **Zero-Copy Hub-Spoke 아키텍처**
+   - **Hub**: 단일 진실 공급원인 `AGENTS.md` (글로벌 룰)
+   - **Spoke**: `PROJECT_RULE.md` 등 워크스페이스별 로컬 규칙
+   - **효과**: IDE별(Cursor, Copilot, Windsurf) 설정 파일 중복을 제거하고, 에이전트가 오직 하나의 규약만 바라보게 하여 지시 사항의 충돌과 환각을 원천 차단합니다.
+
+2. **티켓 주도 워크플로우 (TDW: Ticket-Driven Workflow)**
+   - 계획(Plan) → 실행(Execute) → 검증(Verify) → 보관(Archive)의 분명한 라이프사이클로 작업을 이끕니다.
+   - 활성화된 티켓(`ACTIVE_TICKET.md`)을 중심으로 변경을 연결해 범위와 진행 상태가 계속 보이게 합니다.
+
+3. **플랫폼 공존 및 모드 인지형 게이트 (Mode-Aware Workflow Gate)**
+   - 에이전트의 현재 모드(Plan Mode vs. Execute Mode)를 인지하여, Plan Mode에서는 분석과 구현 계획서(Artifacts) 작성에 집중하도록 APC를 적용합니다.
+   - MCP(Model Context Protocol) Soft Gate와 연동되어 현재 티켓 컨텍스트에 맞는 변경 흐름을 유지합니다.
+
+4. **지식 증류 및 Zero-Legacy (Knowledge Distillation)**
+   - 완료된 작업은 `reports/`로 아카이빙되며, 이 과정에서 **Zero-Token 지식 증류** 기술이 적용되어 핵심 히스토리만 벡터 DB(DeukAgentContext)로 전달됩니다.
+   - 불필요한 과거 로그나 사용되지 않는 `.cursorrules` 스텁을 자동으로 청소하여 컨텍스트 윈도우 낭비를 막습니다.
+
+### 지침 파일만으로 부족한 이유
+
+이미 AI 코딩 에이전트 생태계에는 `AGENTS.md`, GitHub Copilot instructions, Cursor rules, Claude skills, 여러 에이전트 실행 도구, 일반 LLM 가드레일이 있습니다. Deuk Agent Flow는 이들과 경쟁하기보다 그 위에 **티켓 기반 레포 흐름**을 얹습니다.
+
+| 비슷한 접근 | 도움이 되는 부분 | Deuk Agent Flow가 더하는 것 |
+|---|---|---|
+| `AGENTS.md` 공개 형식 | 코딩 에이전트가 읽을 공통 지침 파일 | 티켓 생명주기, Phase Gate, 검증, 아카이브 가능한 기억 |
+| Copilot instructions / Cursor rules / Claude memory | 도구별 맞춤 지침 | 여러 에이전트가 공유하는 레포 소유 워크플로우 |
+| Claude/Copilot custom agent와 skill | 재사용 가능한 작업 playbook | skill이 워크플로우를 대체하지 않고 티켓 실행으로 들어가게 함 |
+| 에이전트 실행기와 harness | 여러 코딩 에이전트 실행 | 어떤 에이전트를 쓰든 레포 안에서 생명주기를 통제 |
+| 일반 LLM/MCP 가드레일 | 런타임 정책 검사 | 작업 지시서, 범위 계약, 깃에 남는 기록, 완료 근거 |
+
+Deuk Agent Flow는 AI 코딩 작업을 팀이 이해하고 이어받기 쉬운 흐름으로 만들고 싶을 때 특히 잘 맞습니다. 여러 파일에 걸친 변경, 검증, 기록, 다음 작업 연결이 자연스럽게 이어지도록 돕는 데 초점을 둡니다.
+
+### Karpathy식 skill과 같이 쓰면 좋은 점
+
+Karpathy식 skill은 한 작업 안에서 에이전트의 행동을 더 좋게 만드는 데 강합니다. Deuk Agent Flow는 그 작업을 레포 차원에서 티켓화하고, 범위를 맞추고, 검증하고, 다시 찾을 수 있게 남기는 데 강합니다.
+
+둘을 함께 쓰면 skill은 작업 수행 품질을 끌어올리고, Deuk Agent Flow는 그 결과를 팀 흐름에 연결합니다. 앞단에서는 행동 playbook이 작동하고, 뒷단에서는 티켓 생명주기와 DeukAgentContext 기억 계층이 남습니다.
+
+### 다음 개선 방향
+
+다음 단계는 이 워크플로우를 더 잘 보이고 더 쉽게 도입하게 만드는 것입니다. 첫 실행 점검을 더 명확히 하고, CLI/RAG 결과에 짧은 재각인 신호를 붙이며, README/npm 포지셔닝을 강화하고, active ticket, phase, open ticket count, DeukAgentContext memory status를 보여주는 companion 표면을 준비하는 방향입니다. 목표는 팀이 쓰는 코딩 에이전트를 바꾸지 않고도 같은 작업 규율을 자연스럽게 얻는 것입니다.
+
+### 📚 상세 문서
+| 문서 | 용도 |
+|---|---|
+| [docs/usage-guide.ko.md](docs/usage-guide.ko.md) | **[추천]** 실전 배포 및 단계별 사용 가이드 |
+| [docs/architecture.ko.md](docs/architecture.ko.md) | 고수준 시스템 구조 및 시각적 인포그래픽 |
+| [docs/how-it-works.ko.md](docs/how-it-works.ko.md) | 상세 CLI 메커니즘, 초기화 생명주기 및 파일 역할 |
+| [docs/principles.ko.md](docs/principles.ko.md) | 설계 철학: Hub-Spoke, Zero-Legacy, 소스 주권 |
+| **English Docs** | [README.md](README.md) · [docs/architecture.md](docs/architecture.md) |
+
+---
+
+## 🚀 빠른 시작 (Quick Start)
+
+가장 빠르게 Deuk Agent Flow를 현재 작업 프로젝트에 도입하는 방법입니다.
+
+```bash
+# 1. 글로벌 설치
+npm install -g deuk-agent-flow
+
+# 2. 프로젝트 초기화 (AGENTS.md 및 설정 생성)
+deuk-agent-flow init
+```
+
+이후 일상 작업은 명령을 직접 치기보다 에이전트에게 짧게 말합니다. 예: "진행", "다음", "원인 다시 파악".
+
+여러 프로젝트를 한 `~/workspace` 아래에서 관리한다면 각 프로젝트 루트에서 `deuk-agent-flow init`을 실행합니다. workspace 루트는 공통 포인터 역할을 할 수 있지만, 실제 작업 티켓과 로컬 규칙은 보통 각 프로젝트의 `.deuk-agent/`와 `PROJECT_RULE.md`가 소유합니다.
+
+이렇게 사용하면 효과가 극대화됩니다. workspace 루트는 공통 진입점, 각 프로젝트 루트는 독립 티켓/규칙/검증 단위로 나누고, 중첩 서버나 앱은 필요할 때 별도 프로젝트로 초기화하세요.
+
+자세한 실전 활용법은 **[실전 사용 가이드](docs/usage-guide.ko.md)**를 참조하세요.
+
+## 🛠️ 설치 및 설정
+
+### 1. 글로벌 설치 (일반 사용자)
+`npx` 캐시 문제와 "로컬 트랩"을 방지하기 위해 글로벌 설치가 엄격히 권장됩니다.
+
+```bash
+npm install -g deuk-agent-flow
+deuk-agent-flow init
+```
+
+### 2. 로컬 소스 개발 (메인테이너/파워 유저)
+v3.0은 **Global CLI Proxy**를 도입했습니다. `DeukAgentFlow` 워크스페이스 내부에서 개발 중이라면, 글로벌 명령이 자동으로 로컬 소스로 실행을 위임합니다.
+
+```bash
+cd ~/workspace/DeukAgentFlow
+sudo npm link
+deuk-agent-flow init  # 자동으로 로컬 scripts/cli.mjs로 라우팅됨
+```
+
+Codex나 Copilot을 주로 사용한다면 이 구성이 일상 운영에 가장 적합합니다. 현재는 이 두 환경에서 Hub-Spoke와 티켓 기반 워크플로우가 가장 부드럽게 동작합니다.
+
+### 3. 메인테이너 배포
+메인테이너는 루트에서 한 번의 명령으로 배포할 수 있습니다.
+
+```bash
+npm run publish
+```
+
+이 흐름은 한 번의 실행으로 `deuk-flow` 릴리스 표면 아래 npm 패키지 두 개를 모두 등록해야 합니다.
+
+- `deuk-flow` canonical 패키지: `deuk-agent-flow`
+- `deuk-flow` 레거시 호환 alias 패키지: `deuk-agent-rule`
+
+배포 스크립트는 먼저 alias 패키지의 version/dependency를 동기화하고, 그 다음 canonical 패키지를 publish한 뒤 alias 패키지를 publish합니다.
+
+npm registry에 쓰기 전에 dry-run으로 먼저 확인하세요.
+
+```bash
+npm run publish:dry
+```
+
+배포 전에는 Docker consumer smoke test를 실행합니다. 이 검증은 깨끗한 Node 컨테이너에 packed package를 설치하므로, 로컬 `npm link`나 global package가 의존성 누락을 숨기지 못합니다.
+
+```bash
+npm run smoke:npm:docker
+```
+
+배포 후 필요하면 통합 다운로드 배지를 갱신합니다.
+
+```bash
+npm run badge:downloads
+```
+
+이 배지는 표기상 `deuk-flow`를 사용하되, `deuk-agent-flow`와 `deuk-agent-rule` 다운로드 수를 같은 total에 합산합니다.
+
+---
+
+## 🎯 프로토콜 워크플로우
+
+워크플로우는 **티켓 기반 실행 계약(Ticket-Driven Execution Contract)**에 의해 통제됩니다.
+
+1. **스캐폴딩 (Scaffolding)**: `init` 명령어가 프로젝트의 성격을 파악하고 `.deuk-agent/templates/`와 `AGENTS.md` (혹은 `PROJECT_RULE.md` 포인터)를 자동 배치합니다.
+2. **티켓팅 (Plan Phase)**: 사용자가 짧게 지시하면 에이전트가 맥락을 읽고 내부 작업 지시서를 생성합니다. 이때 에이전트는 Plan Mode로 동작하며 코드를 수정할 수 없고 계획 수립에만 집중합니다.
+3. **실행 (Execute Phase)**: 사용자의 승인을 받은 후, 에이전트는 **타겟 서브모듈**에 고정되어 실질적인 코드 작성을 수행합니다. MCP Soft Gate가 인가되지 않은 파일의 수정을 감시합니다.
+4. **검증 (Verify Phase)**: 개발 작업 종료 전 사이드 이펙트 감사(Audit) 및 컨벤션(DC-DUP 등 아키텍처 규칙) 체크를 수행합니다.
+5. **아카이빙 (Archive Phase)**: 완료된 티켓은 Zero-Token 지식 증류를 거쳐 `reports/`로 이동하며, 이 데이터는 DeukAgentContext 벡터 데이터베이스에 저장되어 영구적인 **엔지니어링 메모리 엔진**으로 작동합니다.
+
+---
+
+## ⚙️ 에이전트에게 말로 요청하기
+
+일상 사용자는 티켓 명령을 외울 필요가 없습니다. 짧게 말하면 에이전트가 맥락, CLI, 티켓 파일을 처리합니다.
+
+| 하고 싶은 일 | 이렇게 말해도 됨 |
+|--------|------|
+| 새 작업 시작 | *"티켓 잡고 진행"* |
+| 기존 작업 이어가기 | *"다음 진행"* |
+| 코딩 전 검토 | *"원인 먼저 파악"* |
+| 완료 처리 | *"검증 기록하고 정리"* |
+| skill 관리 | *"safe-refactor 추가"* |
+
+### 티켓 파일 깃 관리 원칙
+
+- `.deuk-agent/tickets/**/*.md`와 `INDEX*.json`은 CLI가 바꾼 결과만 반영합니다.
+- 티켓 본문만 커밋하고 index를 빼먹지 마세요. 다음 작업에서 상태가 맞지 않을 수 있습니다.
+- 생성이 실패한 뒤 티켓 파일을 손으로 만들거나 frontmatter로 상태를 바로 바꾸지 마세요.
+- `telemetry.jsonl`은 보통 실행 로그이므로 일반 코드 커밋에는 넣지 않는 편이 낫습니다.
+- 작업을 마쳤다면 가능하면 `ticket archive`까지 끝낸 뒤 커밋해 active/archive 흐름이 함께 남도록 하세요.
+
+메인테이너와 자동화 환경에서는 `deuk-agent-flow ticket create`, `ticket move`, `ticket archive` 같은 CLI 명령을 직접 사용할 수 있습니다.
+
+자세한 사용 예시는 [docs/usage-guide.ko.md](docs/usage-guide.ko.md)를 참고하세요.
+
+---
+
+## 관련 아이디어와 영감
+
+Deuk Agent Flow는 [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)처럼
+AI 코딩 에이전트가 잘못 가정하고, 과하게 구현하고, 요청 밖 코드를 수정하는 문제의식과 맞닿아 있습니다.
+
+다만 Deuk Agent Flow는 프롬프트 수준의 지침 파일을 넘어 티켓, Phase Gate,
+스코프 계약, 검증, 아카이브 가능한 엔지니어링 메모리까지 제공하는 레포 단위 워크플로우 계층입니다.
+
+first-party skill MVP는 이 경계를 명확히 유지합니다. skill은 반복 실패 패턴을 다루는 짧은
+`SKILL.md` playbook이고, workflow 권한의 단일 기준은 계속 `core-rules/AGENTS.md`입니다.
+`skill add`와 `skill expose`로 Claude/Cursor에 playbook을 노출하되, 전체 rule contract를 복사하지 않습니다.
+
+스킬 제공 방식:
+
+- `init` 시 전체 first-party skill 템플릿이 `.deuk-agent/skill-templates/`로 동기화됩니다.
+- 기본 추천 장착: `safe-refactor`, `generated-file-guard`.
+- 선택 장착: `context-recall`, `project-pilot`.
+
+현재 first-party skill:
+
+| skill | 용도 |
+|---|---|
+| `safe-refactor` | 기본 추천: 작은 리팩터링을 범위/테스트 안에 묶기 |
+| `generated-file-guard` | 기본 추천: generated output 직접 수정 방지 |
+| `context-recall` | 선택: 과거 티켓/결정/실패 패턴 재사용 |
+| `project-pilot` | 선택: cross-language, protocol, generated/runtime drift 정리 |
+
+```bash
+npx deuk-agent-flow init
+npx deuk-agent-flow skill list
+npx deuk-agent-flow skill add --skill safe-refactor
+npx deuk-agent-flow skill add --skill generated-file-guard
+npx deuk-agent-flow skill add --skill project-pilot
+npx deuk-agent-flow skill expose --platform claude
+```
+
+---
+
+### 🏷️ 검색 태그
+`#AI-Orchestration` `#Agentic-Workflow` `#DeukFamily` `#Engineering-Intelligence` `#Zero-Legacy` `#High-Signal-Coding` `#AI-Protocol` `#CursorRules` `#CopilotInstructions` `#ClaudeCode` `#ClaudeMD` `#AgentsMD` `#AgentSkills` `#CodingAgent` `#AI-Guardrails` `#LLM-Control-Plane`

package/README.md

@@ -0,0 +1,270 @@
+<div align="center">
+  <br />
+  <img src="docs/assets/architecture-v3.png" width="800" alt="DeukAgentFlow Architecture" />
+  <br />
+  <h1>Deuk Agent Flow v4.0.0</h1>
+  <p>
+    <a href="https://www.npmjs.com/package/deuk-agent-flow"><img src="https://img.shields.io/npm/v/deuk-agent-flow.svg?label=deuk-flow" alt="deuk-flow npm version" /></a>
+  </p>
+  <p><b>Stop losing AI coding work between chats.</b></p>
+  <p><i>Say "next" or "ship it"; Deuk Agent Flow keeps the ticket, scope, verification, and memory attached to your repo.</i></p>
+  <p>Part of the <a href="https://deukpack.app">Deuk Family</a> ecosystem.</p>
+  <p><a href="README.ko.md">한국어</a> · <a href="README.md">English</a></p>
+</div>
+
+---
+
+**Deuk Agent Flow** is the repo-owned workflow layer for AI coding agents: Codex, Copilot, Cursor, Claude Code, Gemini, Windsurf, or the next agent you adopt can enter the same ticketed flow.
+
+Most agent setups stop at instructions. Deuk Agent Flow turns short chat into an operating loop: ticket, scope, execute, verify, archive. It keeps `AGENTS.md`, Copilot instructions, Cursor rules, Claude skills, and related agent surfaces aligned without asking you to type long commands.
+
+The hook is simple: you can say "next", "inspect", or "clean this up", and the current agent has a repo-owned place to know what that means. Active work lives in `.deuk-agent/tickets/`; decisions, plans, and closeout evidence stay with the codebase instead of vanishing into a chat transcript. **Deuk Agent Flow** is the workflow layer. Plug that flow into the separate companion product **Deuk AgentContext**, and the whole repo gains an expanded project brain: searchable memory, reusable decisions, and team patterns the next agent can actually use.
+
+### Why Now
+
+AI coding has crossed from novelty into production volume:
+
+- Google says **75% of its new code is AI-generated**, up from 25% in 2024 and 50% last fall. ([Semafor, 2026](https://www.semafor.com/article/04/24/2026/google-ceo-says-75-of-companys-new-code-is-ai-generated))
+- Sonar's 2026 developer survey coverage reports AI-generated code at about **42% today**, with developers expecting roughly **65% by 2027**. ([TechRadar, 2026](https://www.techradar.com/pro/devs-dont-trust-ai-code-but-many-say-they-still-dont-check-it-anyways))
+- Stack Overflow's 2025 survey coverage found **84%** of developers use or plan to use AI tools, while "almost right" output and debugging AI code are top frustrations. ([InfoWorld, 2025](https://www.infoworld.com/article/4031673/ai-use-among-software-developers-grows-but-trust-remains-an-issue-stack-overflow-survey.html))
+- Faros reported the uncomfortable tradeoff: more completed work, but **54% more bugs per developer**, review time up fivefold, and more incidents per PR. ([ADTmag, 2026](https://adtmag.com/articles/2026/04/22/more-code-more-bugs.aspx))
+
+The new bottleneck is not typing code. It is keeping agent work scoped, reviewable, verified, and recoverable.
+
+### What Changes With Deuk Agent Flow
+
+| Without it | With Deuk Agent Flow |
+|---|---|
+| "Continue" depends on chat memory | "Next" resolves through repo tickets |
+| Agent edits can drift outside the ask | APC scope defines what can change |
+| Reviewers see code but not intent | Tickets keep cause, plan, and evidence beside the code |
+| AI output adds review load | Verification and closeout are part of the work loop |
+| Context dies when the chat ends | Archive + knowledge distillation preserve the project memory |
+
+### One-Minute View
+
+```text
+Short chat
+  "next" / "inspect" / "ship it"
+        |
+        v
+Deuk Agent Flow
+  ticket + scope + verification + memory
+        |
+        v
+Repo-owned work
+  reviewable changes + durable decisions + next-session continuity
+```
+
+| Benefit | What you feel |
+|---|---|
+| Less context loss | The next agent can continue without replaying the whole chat |
+| Less scope drift | The ticket says what can and cannot change |
+| Less review guesswork | Intent and evidence sit beside the diff |
+| Less generated-code risk | Source/generator ownership is checked before edits |
+| Better team memory | Completed work becomes searchable project history |
+
+> **Current readiness:**
+> v4.0.0 is deployment-ready for agent-driven repositories. It is currently most reliable in **OpenAI Codex** and **GitHub Copilot** workflows. Cursor, Windsurf, Claude Code, and MCP remain supported through pointer-style integration, but they should be validated per workspace before rollout. MCP server registration is separate from `init`.
+> **Architecture foundation:**
+> We have officially deprecated monolithic `.cursorrules`. v3.0 introduces the **Hub-Spoke model** where `AGENTS.md` is the single source of truth, and IDE-specific rules act as thin entry-point pointers.
+
+### 🗺️ Main Features & Architecture
+
+Deuk Agent Flow brings four core capabilities to day-to-day AI engineering:
+
+1. **Zero-Copy Hub-Spoke Architecture**
+   - **Hub**: `AGENTS.md` acts as the global single source of truth.
+   - **Spoke**: IDE-specific rules (like `.cursorrules`) or `PROJECT_RULE.md` act as thin pointers.
+   - **Benefit**: Eliminates rule duplication, preventing conflicting instructions and context hallucination across different IDEs (Cursor, Copilot, Windsurf).
+
+2. **Ticket-Driven Workflow (TDW)**
+   - Guides work through a clear lifecycle: Plan → Execute → Verify → Archive.
+   - Keeps changes connected to an active ticket in `.deuk-agent/tickets/`, so scope and progress stay visible.
+
+3. **Platform Co-existence & Mode-Aware Workflow Gate**
+   - Uses strong Agent Permission Contracts (APC) through a **Mode-Aware** workflow.
+   - In **Plan Mode**, agents focus on analysis and planning artifacts before moving into approved execution.
+   - Integrates with MCP Soft Gates to keep code changes aligned with the current ticket context.
+
+4. **Zero-Token Knowledge Distillation**
+   - When a ticket is archived, it is distilled into a zero-token summary and moved to `reports/`.
+   - These reports are vectorized into DeukAgentContext, building a permanent Engineering Memory Engine without cluttering the agent's active context window.
+
+### Why Not Just Instructions?
+
+The agent tooling space already has useful building blocks: `AGENTS.md`, GitHub Copilot instructions, Cursor rules, Claude skills, agent launchers, and general LLM guardrail frameworks. Deuk Agent Flow is positioned one layer above plain instruction sync: it turns those surfaces into a ticketed repository workflow.
+
+| Similar approach | What it helps with | Deuk Agent Flow adds |
+|---|---|---|
+| `AGENTS.md` open format | A predictable instruction file for coding agents | Ticket lifecycle, phase gates, verification, and archiveable memory |
+| Copilot instructions / Cursor rules / Claude memory | Tool-specific guidance | One repo-owned workflow shared across agent clients |
+| Claude or Copilot custom agents and skills | Reusable task playbooks | Skills route into scoped, ticketed execution instead of replacing the workflow |
+| Agent launchers and harnesses | Running many coding agents from one place | Lifecycle control inside the repository, independent of the chosen agent |
+| General LLM/MCP guardrails | Runtime policy checks for AI systems | Developer-facing work orders, scope contracts, Git-visible history, and closeout evidence |
+
+Use Deuk Agent Flow when you want AI coding work to stay coordinated, reviewable, and easy to carry forward across sessions and teammates.
+
+### Better Together With Karpathy-Style Skills
+
+Karpathy-style skills are great at improving how an agent behaves inside a task. Deuk Agent Flow is great at making that task ticketed, scoped, verified, and remembered at the repository level.
+
+Used together, skills can improve the quality of the move, while Deuk Agent Flow keeps the move connected to team workflow. The result is a better session and a better project record: behavior playbooks on the front end, ticket lifecycle and DeukAgentContext memory on the back end.
+
+### What's Next
+
+The next step is to make this flow even easier to see and adopt: clearer first-run checks, compact CLI/RAG reminders for agents, stronger README/npm positioning, and companion surfaces that show active ticket, phase, open-ticket count, and DeukAgentContext memory status without asking teams to switch coding agents.
+
+### 📚 Detailed Documentation
+| Doc | Purpose |
+|---|---|
+| [docs/architecture.md](docs/architecture.md) | High-level system structure and visual infographics |
+| [docs/how-it-works.md](docs/how-it-works.md) | Detailed CLI mechanics, initialization lifecycle, and file roles |
+| [docs/principles.md](docs/principles.md) | Design philosophy: Hub-Spoke, Zero-Legacy, and Source Sovereignty |
+| **Korean Docs** | [README.ko.md](README.ko.md) · [docs/architecture.ko.md](docs/architecture.ko.md) |
+
+---
+
+## 🛠️ Installation & Setup
+
+### 1. Global Installation (Standard User)
+To prevent `npx` cache issues and "Local Traps", a global installation is strictly required.
+
+```bash
+npm install -g deuk-agent-flow
+deuk-agent-flow init
+```
+
+If you manage many repos under one workspace, run `deuk-agent-flow init` in each project root that owns its own rules and tickets. The workspace root can act as a shared pointer, but day-to-day work usually belongs to each project's `PROJECT_RULE.md` and `.deuk-agent/`.
+
+This is where the effect compounds: use the workspace root as the shared entry point, each project root as an independent ticket/rule/verification boundary, and nested apps or servers as separate projects only when they have their own lifecycle.
+
+### 2. Local Source Development (Maintainer/Power User)
+v3.0 introduces a **Global CLI Proxy**. If you are developing inside the `DeukAgentFlow` workspace, the global command will automatically delegate execution to your local source.
+
+```bash
+cd ~/workspace/DeukAgentFlow
+sudo npm link
+deuk-agent-flow init  # Routes to local scripts/cli.mjs automatically
+```
+
+If you primarily work in Codex or Copilot, this is the recommended day-to-day setup. Those clients currently have the smoothest behavior with the hub-spoke and ticket-driven workflow.
+
+### 3. Maintainer Publish
+Maintainers can publish from the root command:
+
+```bash
+npm run publish
+```
+
+This flow must register both npm packages in one run under the `deuk-flow` release surface:
+
+- `deuk-flow` canonical package: `deuk-agent-flow`
+- `deuk-flow` legacy compatibility alias package: `deuk-agent-rule`
+
+The publish script syncs the alias package version/dependency first, then publishes the canonical package before the alias package.
+
+Use dry-run mode before writing to the npm registry:
+
+```bash
+npm run publish:dry
+```
+
+Before publishing, run the Docker consumer smoke test. It installs the packed packages into a clean Node container, so local `npm link` or global packages cannot hide missing dependencies.
+
+```bash
+npm run smoke:npm:docker
+```
+
+After publish, refresh the combined downloads badge when needed:
+
+```bash
+npm run badge:downloads
+```
+
+The badge should display `deuk-flow` while still summing downloads from both `deuk-agent-flow` and `deuk-agent-rule`.
+
+---
+
+## 🎯 The Protocol Workflow
+
+The workflow is governed by a **Ticket-Driven Execution Contract**.
+
+1. **Scaffolding**: `init` deploys `.deuk-agent/templates/` and `AGENTS.md` (or local pointers like `PROJECT_RULE.md`).
+2. **Ticketing (Plan Phase)**: The user describes the work in natural language, and the agent turns it into a bounded work order in `.deuk-agent/tickets/`. During this phase, agents operate in **Plan Mode** and are restricted from mutating files.
+3. **Execution (Execute Phase)**: Once authorized, the AI agent reads the ticket, locks onto the **Target Submodule**, and executes code changes. MCP Soft Gates ensure that unauthorized modifications are blocked.
+4. **Verification**: The agent performs a side-effect audit and convention (e.g., DC-DUP) check before closure.
+5. **Archiving (Archive Phase)**: Completed tickets undergo Zero-Token Knowledge Distillation and move to `reports/` to build the **Engineering Memory Engine** via DeukAgentContext.
+
+---
+
+## ⚙️ Agent Requests
+
+Ask your AI agent in plain language. The CLI commands are the agent's execution layer, not something the user has to type during normal collaboration.
+
+| What you want | Say something like |
+|--------|------|
+| Start a scoped task | *"티켓 잡고 진행"* |
+| Continue existing work | *"다음 진행"* |
+| Review before coding | *"원인 먼저 파악"* |
+| Finish and preserve context | *"검증 기록하고 정리"* |
+| Manage skills | *"safe-refactor 추가"* |
+
+### Ticket File Git Hygiene
+
+- Treat `.deuk-agent/tickets/**/*.md` and `INDEX*.json` as CLI-managed lifecycle artifacts.
+- Do not commit a ticket body without the related index updates. The next session can restore the wrong active/archive state.
+- After `ticket create` fails, do not create or repair ticket files manually.
+- Do not flip ticket status by editing frontmatter directly. Use `ticket move`, `ticket close`, or `ticket archive`.
+- `telemetry.jsonl` is usually operational log noise, so it is better left out of normal code commits unless your repo intentionally tracks it.
+- When possible, commit completed work after `ticket archive` so the active/archive transition lands in one history step.
+
+For maintainers and automation, the underlying CLI still exposes commands such as `deuk-agent-flow ticket create`, `ticket move`, and `ticket archive`.
+
+For more day-to-day examples, see [docs/how-it-works.md](docs/how-it-works.md).
+
+---
+
+## Related Ideas & Inspiration
+
+Deuk Agent Flow shares the same concern as guideline-first projects like
+[andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills):
+AI coding agents often over-assume, over-engineer, and edit outside the requested scope.
+
+Where prompt-level guideline files improve agent behavior inside one client,
+Deuk Agent Flow adds a repository-level workflow layer: tickets, phase gates,
+scoped permissions, verification, and archiveable engineering memory.
+
+The first-party skill MVP keeps that boundary explicit: skills are short
+`SKILL.md` playbooks for recurring failure patterns, while `core-rules/AGENTS.md`
+remains the workflow authority. Use `skill add` and `skill expose` to make those
+playbooks visible to Claude or Cursor without copying the full rule contract.
+
+Skill availability:
+
+- Synced by `init`: all first-party skill templates are copied into `.deuk-agent/skill-templates/`.
+- Recommended default install: `safe-refactor`, `generated-file-guard`.
+- Optional install: `context-recall`, `project-pilot`.
+
+Current first-party skills:
+
+| Skill | Use when |
+|---|---|
+| `safe-refactor` | Default recommended: keep refactors small, scoped, and test-backed |
+| `generated-file-guard` | Default recommended: avoid direct edits to generated outputs |
+| `context-recall` | Optional: reuse prior ticket/rule memory without making RAG the source of truth |
+| `project-pilot` | Optional: control cross-language, protocol, generated/runtime drift refactors |
+
+```bash
+npx deuk-agent-flow init
+npx deuk-agent-flow skill list
+npx deuk-agent-flow skill add --skill safe-refactor
+npx deuk-agent-flow skill add --skill generated-file-guard
+npx deuk-agent-flow skill add --skill project-pilot
+npx deuk-agent-flow skill expose --platform claude
+```
+
+---
+
+### 🏷️ Keywords
+`#AI-Orchestration` `#Agentic-Workflow` `#DeukFamily` `#Engineering-Intelligence` `#Zero-Legacy` `#High-Signal-Coding` `#AI-Protocol` `#CursorRules` `#CopilotInstructions` `#ClaudeCode` `#ClaudeMD` `#AgentsMD` `#AgentSkills` `#CodingAgent` `#AI-Guardrails` `#LLM-Control-Plane`

package/bin/deuk-agent-flow.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Global Proxy for DeukAgentFlow CLI
+ * Routes to the local workspace source when present so global installs and
+ * temporary npx packages do not shadow active local development.
+ */
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function findWorkspaceRoot(currentDir) {
+  let dir = currentDir;
+  while (true) {
+    if (fs.existsSync(path.join(dir, "DeukAgentFlow", "scripts", "cli.mjs"))) {
+      return dir;
+    }
+    if (fs.existsSync(path.join(dir, "DeukAgentRules", "scripts", "cli.mjs"))) {
+      return dir;
+    }
+    if (fs.existsSync(path.join(dir, ".git")) && (fs.existsSync(path.join(dir, "DeukAgentFlow")) || fs.existsSync(path.join(dir, "DeukAgentRules")))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const wsRoot = findWorkspaceRoot(process.cwd());
+if (wsRoot) {
+  const localCli = fs.existsSync(path.join(wsRoot, "DeukAgentFlow", "scripts", "cli.mjs"))
+    ? path.join(wsRoot, "DeukAgentFlow", "scripts", "cli.mjs")
+    : path.join(wsRoot, "DeukAgentRules", "scripts", "cli.mjs");
+  const bundledCli = path.resolve(path.join(__dirname, "..", "scripts", "cli.mjs"));
+  if (fs.existsSync(localCli) && localCli !== bundledCli) {
+    const args = process.argv.slice(2);
+    const result = spawnSync("node", [localCli, ...args], { stdio: "inherit" });
+    process.exit(result.status !== null ? result.status : 1);
+  }
+}
+
+const myCli = path.join(__dirname, "..", "scripts", "cli.mjs");
+if (fs.existsSync(myCli)) {
+  const args = process.argv.slice(2);
+  const result = spawnSync("node", [myCli, ...args], { stdio: "inherit" });
+  process.exit(result.status !== null ? result.status : 1);
+}
+
+console.error("Error: Could not find DeukAgentFlow CLI script at " + myCli);
+process.exit(1);

package/bin/deuk-agent-rule.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("./deuk-agent-flow.js");