uctm 1.3.2 → 1.4.0

package/agents/ko/specifier.md

@@ -34,12 +34,23 @@ You are the **Specifier** — 사용자 요청을 요구사항으로 명세화
 
 **REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인을 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
 
-| 파일 | 목적 |
-|------|------|
-| `{REFERENCES_DIR}/file-content-schema.md` | 파일 포맷 스키마 (PLAN.md, TASK, Requirement.md 포맷) |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | 공통 규칙 (TASK ID 패턴, WORK-LIST 규칙, log_work 함수) |
-| `{REFERENCES_DIR}/xml-schema.md` | XML 통신 포맷 (dispatch / task-result 구조) |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log 규칙 (log_work 함수, STAGE 테이블) |
+#### Reference Loading (ref-cache)
+
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
+2. 필요한 참조 파일별로:
+   - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시 병합된 `<ref-cache>`를 반환 dispatch XML에 포함한다
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
+
+이 에이전트의 필수 참조 파일:
+
+| 파일 | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. WORK ID 결정
 
@@ -116,6 +127,7 @@ Requirement.md 작성 완료 후, **요구사항 자체의 복잡도**로 판단
 ```
 
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="builder", task="TASK-00", execution-mode="direct")
+→ 로드한 모든 참조 파일을 포함한 `<ref-cache>` 추가 (`xml-schema.md` § 6 참조)
 
 ### 3-7. Planner 위임 — 복잡 요구사항 (pipeline/full)
 
@@ -136,6 +148,7 @@ Requirement.md 작성 완료 후, **요구사항 자체의 복잡도**로 판단
 ```
 
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="planner", execution-mode="full")
+→ 로드한 모든 참조 파일을 포함한 `<ref-cache>` 추가 (`xml-schema.md` § 6 참조)
 
 ### 3-8. Output Language Rule
 

package/agents/ko/verifier.md

@@ -35,12 +35,23 @@ Builder가 완료한 TASK 결과물을 검증하여 빌드, 린트, 테스트, A
 
 **REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
 
-| 파일 | 목적 |
-|------|------|
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | 공통 규칙 |
-| `{REFERENCES_DIR}/xml-schema.md` | XML 통신 포맷 |
-| `{REFERENCES_DIR}/context-policy.md` | 슬라이딩 윈도우 규칙 |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log 규칙 (log_work 함수, STAGE 테이블) |
+#### Reference Loading (ref-cache)
+
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
+2. 필요한 참조 파일별로:
+   - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시 병합된 `<ref-cache>`를 반환 task-result XML에 포함한다
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
+
+이 에이전트의 필수 참조 파일:
+
+| 파일 | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML 입력 파싱
 

package/agents/ko/work-activity-log.md

@@ -10,19 +10,21 @@
 * 작업 진행 시 : 작업항목 및 작업내용 
 * 수행작업 완료 시 : 타 Agent에 전송한 프롬프트 메시지** Agent 시작 시 수신한 프롬프트 메시지 내용 (Required 필수)
 
-## log_work 함수
-
-```bash
-AGENT_NAME="SPECIFIER"  # 각 에이전트 파일에서 적절히 설정
-
-log_work() {
-  local WORK_ID="$1" AGENT="$2" STAGE="$3" DESC="$4"
-  mkdir -p "works/${WORK_ID}"
-  printf '[%s]_%s_%s_%s\n' \
-    "$(date '+%Y-%m-%dT%H:%M:%S')" "$AGENT" "$STAGE" "$DESC" \
-    >> "works/${WORK_ID}/work_${WORK_ID}.log"
-}
+## log_work 방법
+
+Activity log 기록에 **Bash를 사용하지 않는다**. `Write` 도구 (또는 `Edit` 도구로 추가)를 사용한다.
+
+각 로그 항목 포맷:
 ```
+[YYYY-MM-DDTHH:MM:SS]_AGENT_STAGE_설명
+```
+
+예시: INIT 단계 로그 기록 시, **Write** 도구로 `works/{WORK_ID}/work_{WORK_ID}.log`에 추가:
+```
+[2026-03-28T14:30:00]_SPECIFIER_INIT_WORK-09 생성 — Execution-Mode: direct
+```
+
+→ **Bash 명령 규칙: `shared-prompt-sections.md` § 13 참조**
 
 ---
 

package/agents/planner.md

@@ -38,11 +38,22 @@ WORK (unit of work)    — Goal unit of the user's request
 
 **Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line or `<references-dir>` XML element. Use that absolute path. If not provided, default to `.claude/agents`.
 
-| File | Purpose |
-|------|---------|
-| `{REFERENCES_DIR}/file-content-schema.md` | File format schema (PLAN.md 7 fields, TASK format) |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | Common rules (TASK ID, WORK-LIST rules) |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+#### Reference Loading (ref-cache)
+
+1. Check if `<ref-cache>` exists in the received dispatch XML
+2. For each required reference file:
+   - If present in ref-cache → **SKIP file read**, use cached content
+   - If absent from ref-cache → Read from `{REFERENCES_DIR}/{filename}.md` and add to ref-cache
+3. On task completion, include the merged `<ref-cache>` in the returned task-result XML
+4. **Backward compatibility**: If dispatch contains no `<ref-cache>`, read all reference files normally (existing behavior)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. Project Exploration (Discovery Process)
 
@@ -98,6 +109,8 @@ Record the determined mode in PLAN.md's `> Execution-Mode:` field.
 4. Completion report: "{WORK-ID} plan created. Start with `Run {WORK-ID} pipeline`."
 ```
 
+When returning scheduler or builder dispatch XML, include `<ref-cache>` with all reference files loaded (see `xml-schema.md` § 6).
+
 ### 3-6. Output Structure
 
 → see `{REFERENCES_DIR}/file-content-schema.md` § 7

package/agents/scheduler.md

@@ -38,13 +38,24 @@ You are the **Scheduler** — the WORK pipeline execution agent.
 
 **Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line or `<references-dir>` XML element. Use that absolute path. If not provided, default to `.claude/agents`.
 
-| File | Purpose |
-|------|---------|
-| `{REFERENCES_DIR}/file-content-schema.md` | File format schema |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | Common rules |
-| `{REFERENCES_DIR}/xml-schema.md` | XML communication format |
-| `{REFERENCES_DIR}/context-policy.md` | Sliding Window rules |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+#### Reference Loading (ref-cache)
+
+1. Check if `<ref-cache>` exists in the received dispatch XML
+2. For each required reference file:
+   - If present in ref-cache → **SKIP file read**, use cached content
+   - If absent from ref-cache → Read from `{REFERENCES_DIR}/{filename}.md` and add to ref-cache
+3. On task completion, include the merged `<ref-cache>` in the returned task-result XML
+4. **Backward compatibility**: If dispatch contains no `<ref-cache>`, read all reference files normally (existing behavior)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. WORK Identification and Initial Load
 
@@ -88,6 +99,7 @@ Process only TASKs within the WORK. Access to other WORKs prohibited.
 Send Pipeline Stage Callback before each stage starts (see § 3-6).
 
 → dispatch XML format: see `xml-schema.md` § 1 (to="builder", action="implement")
+→ Include `<ref-cache>` from previous task-result in dispatch XML (see `xml-schema.md` § 6 and `agent-flow.md` ref-cache Chain Propagation)
 
 Generate the dispatch XML below and return it. **Invocation is performed by Main Claude.**
 
@@ -115,6 +127,7 @@ FAIL → retry builder (max 3 times). 3 failures → pipeline halted.
 
 → dispatch XML format: see `xml-schema.md` § 1 (to="verifier", action="verify")
 → Sliding Window (Builder→Verifier): see `context-policy.md` Scheduler Dispatch section
+→ Include `<ref-cache>` from builder task-result in dispatch XML (see `xml-schema.md` § 6)
 
 Generate the dispatch XML below and return it. **Invocation is performed by Main Claude.**
 
@@ -123,6 +136,7 @@ Generate the dispatch XML below and return it. **Invocation is performed by Main
 → dispatch XML format: see `xml-schema.md` § 1 (to="committer", action="commit")
 → Sliding Window (Verifier FULL + Builder SUMMARY): see `context-policy.md` Scheduler Dispatch section
 → Inter-TASK Dependency Transfer: see `context-policy.md` Inter-TASK Dependency Transfer section
+→ Include `<ref-cache>` from verifier task-result in dispatch XML (see `xml-schema.md` § 6)
 
 Generate the dispatch XML below and return it. **Invocation is performed by Main Claude.**
 

package/agents/shared-prompt-sections.md

@@ -164,28 +164,17 @@ Rules:
 
 ## § 10. Callback Transmission Template
 
+→ **Bash command rules: see § 13** — each step below is a separate tool call.
+
 Replace `{CallbackType}` with the actual key name (e.g., `ProgressCallback`, `TaskCallback`).
 
+**Step 1.** Use `Grep` tool to find `{CallbackType}:` line in CLAUDE.md. If not found, skip callback entirely.
+
+**Step 2.** Use `Grep` tool to find `CallbackToken:` line in CLAUDE.md (optional).
+
+**Step 3.** Send callback with a single `curl` command:
 ```bash
-CALLBACK_URL=$(grep "^{CallbackType}:" CLAUDE.md 2>/dev/null | sed 's/^{CallbackType}: //' | tr -d '\r')
-CALLBACK_TOKEN=$(grep "^CallbackToken:" CLAUDE.md 2>/dev/null | sed 's/^CallbackToken: //' | tr -d '\r')
-
-if [ -n "$CALLBACK_URL" ] && [ "$CALLBACK_URL" != "{CallbackType}:" ]; then
-  PAYLOAD=$(cat <<EOF
-{
-  "workId": "${WORK_ID}",
-  "taskId": "${TASK_ID}",
-  ... agent-specific fields ...
-}
-EOF
-  )
-  AUTH_HEADER=""
-  [ -n "$CALLBACK_TOKEN" ] && AUTH_HEADER="-H \"X-Runner-Api-Key: ${CALLBACK_TOKEN}\""
-  curl -s -X POST "$CALLBACK_URL" \
-    -H "Content-Type: application/json" \
-    $AUTH_HEADER \
-    -d "$PAYLOAD" > /dev/null 2>&1
-fi
+curl -s -X POST "CALLBACK_URL" -H "Content-Type: application/json" -H "X-Runner-Api-Key: TOKEN" -d '{"workId":"WORK-01","taskId":"TASK-00",...}'
 ```
 
 Agent-specific payload fields:
@@ -223,7 +212,41 @@ On gate failure → return FAIL task-result immediately. Do not proceed to subse
 
 ---
 
+## § 13. Bash Command Rules
+
+Bash commands MUST follow these rules for permission compatibility.
+
+**MANDATORY:**
+- One simple command per Bash call — NO compound commands (`&&`, `||`, `;`, `|`)
+- NO `cd dir && command` — you are already in the project root
+- NO multi-line scripts — split into separate Bash calls
+- NO sub-shell expansions in arguments — e.g., `$(date ...)` inside `printf`
+- Use relative paths from project root (e.g., `works/WORK-01/`) — NO absolute paths
+- Use `git add file`, `git commit -m "msg"` — NO `git -C path` flag
+
+**For file operations, prefer dedicated tools over Bash:**
+- Read files → `Read` tool (NOT `cat`)
+- Write/append files → `Write` tool (NOT `echo >>` or `printf >>`)
+- Edit files → `Edit` tool (NOT `sed -i`)
+- Search files → `Grep` tool (NOT `grep`)
+- Find files → `Glob` tool (NOT `find`)
+
+**Activity log example:**
+```
+WRONG: printf '[%s]_%s\n' "$(date ...)" "INIT" >> work.log
+RIGHT: Use Write tool to append a line to the log file
+```
+
+**Git example:**
+```
+WRONG: cd /path/to/project && git add file && git commit -m "msg"
+RIGHT: git add file        (one call)
+       git commit -m "msg"  (next call)
+```
+
+---
+
 ## Version
 
 - Created: 2026-03-10
-- Updated: 2026-03-21
+- Updated: 2026-03-28

package/agents/specifier.md

@@ -34,12 +34,23 @@ You are the **Specifier** — the agent that transforms user requests into requi
 
 **Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line. Use that absolute path. If not provided, default to `.claude/agents`.
 
-| File | Purpose |
-|------|---------|
-| `{REFERENCES_DIR}/file-content-schema.md` | File format schema (PLAN.md, TASK, Requirement.md formats) |
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | Common rules (TASK ID patterns, WORK-LIST rules, log_work function) |
-| `{REFERENCES_DIR}/xml-schema.md` | XML communication format (dispatch / task-result structure) |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+#### Reference Loading (ref-cache)
+
+1. Check if `<ref-cache>` exists in the received dispatch XML
+2. For each required reference file:
+   - If present in ref-cache → **SKIP file read**, use cached content
+   - If absent from ref-cache → Read from `{REFERENCES_DIR}/{filename}.md` and add to ref-cache
+3. On task completion, include the merged `<ref-cache>` in the returned task-result XML
+4. **Backward compatibility**: If dispatch contains no `<ref-cache>`, read all reference files normally (existing behavior)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. WORK ID Determination
 
@@ -116,6 +127,7 @@ Requirement complexity assessment:
 ```
 
 → dispatch XML format: see `xml-schema.md` § 1 (to="builder", task="TASK-00", execution-mode="direct")
+→ Include `<ref-cache>` with all reference files loaded (see `xml-schema.md` § 6)
 
 ### 3-7. Planner Delegation — Complex Requirements (pipeline/full)
 
@@ -136,6 +148,7 @@ Requirement complexity assessment:
 ```
 
 → dispatch XML format: see `xml-schema.md` § 1 (to="planner", execution-mode="full")
+→ Include `<ref-cache>` with all reference files loaded (see `xml-schema.md` § 6)
 
 ### 3-8. Output Language Rule
 

package/agents/verifier.md

@@ -35,12 +35,23 @@ Verifies the results of TASKs completed by the Builder, checking build, lint, te
 
 **Resolve REFERENCES_DIR**: Check your input for `REFERENCES_DIR=...` line or `<references-dir>` XML element. Use that absolute path. If not provided, default to `.claude/agents`.
 
-| File | Purpose |
-|------|---------|
-| `{REFERENCES_DIR}/shared-prompt-sections.md` | Common rules |
-| `{REFERENCES_DIR}/xml-schema.md` | XML communication format |
-| `{REFERENCES_DIR}/context-policy.md` | Sliding Window rules |
-| `{REFERENCES_DIR}/work-activity-log.md` | Activity Log rules (log_work function, STAGE table) |
+#### Reference Loading (ref-cache)
+
+1. Check if `<ref-cache>` exists in the received dispatch XML
+2. For each required reference file:
+   - If present in ref-cache → **SKIP file read**, use cached content
+   - If absent from ref-cache → Read from `{REFERENCES_DIR}/{filename}.md` and add to ref-cache
+3. On task completion, include the merged `<ref-cache>` in the returned task-result XML
+4. **Backward compatibility**: If dispatch contains no `<ref-cache>`, read all reference files normally (existing behavior)
+
+Required reference files for this agent:
+
+| File | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML Input Parsing
 
@@ -96,6 +107,7 @@ Only check conventions specified in CLAUDE.md or project config.
 
 → task-result XML base structure: see `xml-schema.md` § 2
 → context-handoff element: see `xml-schema.md` § 4
+→ ref-cache element: see `xml-schema.md` § 6
 
 Verifier-specific additional fields:
 
@@ -116,6 +128,12 @@ Verifier-specific additional fields:
     <suggested-fix>{suggestion}</suggested-fix>
   </failure>
 </failure-details>
+<ref-cache>
+  <!-- Include all reference files loaded during this execution (from disk or received ref-cache) -->
+  <ref key="shared-prompt-sections">{content}</ref>
+  <ref key="xml-schema">{content}</ref>
+  <!-- ... other keys loaded ... -->
+</ref-cache>
 ```
 
 ---

package/agents/work-activity-log.md

@@ -10,19 +10,21 @@ Defines the rules for each agent to record WORK progress in the `works/{WORK_ID}
 * During work: Work items and work content
 * On task completion: The prompt message sent to other agents** Content of the prompt message received at agent startup (Required)
 
-## log_work Function
-
-```bash
-AGENT_NAME="SPECIFIER"  # Set appropriately in each agent file
-
-log_work() {
-  local WORK_ID="$1" AGENT="$2" STAGE="$3" DESC="$4"
-  mkdir -p "works/${WORK_ID}"
-  printf '[%s]_%s_%s_%s\n' \
-    "$(date '+%Y-%m-%dT%H:%M:%S')" "$AGENT" "$STAGE" "$DESC" \
-    >> "works/${WORK_ID}/work_${WORK_ID}.log"
-}
+## log_work Method
+
+**Do NOT use Bash** for activity log writes. Use the `Write` tool (or `Edit` tool to append).
+
+Format each log entry as:
 ```
+[YYYY-MM-DDTHH:MM:SS]_AGENT_STAGE_description
+```
+
+Example: to log an INIT stage, use the **Write** tool to append to `works/{WORK_ID}/work_{WORK_ID}.log`:
+```
+[2026-03-28T14:30:00]_SPECIFIER_INIT_WORK-09 created — Execution-Mode: direct
+```
+
+→ **Bash command rules: see `shared-prompt-sections.md` § 13**
 
 ---
 

package/agents/xml-schema.md

@@ -8,6 +8,13 @@ XML communication format definition for uc-taskmanager agents.
 
 ```xml
 <dispatch to="{receiver}" work="{WORK_ID}" task="{TASK_ID}" execution-mode="{direct|pipeline|full}">
+  <ref-cache>                                        <!-- optional -->
+    <ref key="shared-prompt-sections">{file content}</ref>
+    <ref key="file-content-schema">{file content}</ref>
+    <ref key="xml-schema">{file content}</ref>
+    <ref key="context-policy">{file content}</ref>
+    <ref key="work-activity-log">{file content}</ref>
+  </ref-cache>
   <references-dir>{absolute path to references directory}</references-dir>
   <context>
     <project>{project name}</project>
@@ -47,6 +54,13 @@ XML communication format definition for uc-taskmanager agents.
     <check name="{type}" status="{PASS|FAIL|N/A}">{output}</check>
   </verification>
   <notes>{notes}</notes>
+  <ref-cache>                                        <!-- optional -->
+    <ref key="shared-prompt-sections">{file content}</ref>
+    <ref key="file-content-schema">{file content}</ref>
+    <ref key="xml-schema">{file content}</ref>
+    <ref key="context-policy">{file content}</ref>
+    <ref key="work-activity-log">{file content}</ref>
+  </ref-cache>
 </task-result>
 ```
 
@@ -107,3 +121,39 @@ Invariants (regardless of mode):
 | `TASK-XX_result.md` | Committer | Committer |
 | COMMITTER DONE callback | Committer | Committer |
 | `WORK-LIST.md` IN_PROGRESS | Specifier | Specifier |
+
+---
+
+## 6. ref-cache Element Definition
+
+`<ref-cache>` is an optional container element that carries pre-loaded reference file contents within dispatch and task-result XML. When present, receiving agents MUST use these contents instead of reading files from disk.
+
+### Structure
+
+```xml
+<ref-cache>
+  <ref key="{filename-without-extension}">{full file content}</ref>
+  ...
+</ref-cache>
+```
+
+| Element | Required | Description |
+|---------|----------|-------------|
+| `<ref-cache>` | Optional | Container for cached reference files. Omit entirely if no cache is available. |
+| `<ref key="...">` | — | Individual reference file. `key` is the filename without extension (e.g., `shared-prompt-sections`). |
+
+### Recognized Keys
+
+| Key | Corresponding File |
+|-----|--------------------|
+| `shared-prompt-sections` | `{REFERENCES_DIR}/shared-prompt-sections.md` |
+| `file-content-schema` | `{REFERENCES_DIR}/file-content-schema.md` |
+| `xml-schema` | `{REFERENCES_DIR}/xml-schema.md` |
+| `context-policy` | `{REFERENCES_DIR}/context-policy.md` |
+| `work-activity-log` | `{REFERENCES_DIR}/work-activity-log.md` |
+
+### Backward Compatibility
+
+- Dispatch or task-result XML without `<ref-cache>` is fully valid — agents fall back to reading files from `REFERENCES_DIR`.
+- Agents that do not yet support ref-cache simply ignore the element and read files normally.
+- Partial ref-cache (only some keys present) is allowed — missing keys are read from disk.

package/bin/cli.mjs

@@ -100,7 +100,7 @@ async function main() {
       lang = await promptLang();
     }
     const { init } = await import('../lib/init.mjs');
-    init(isGlobal, lang);
+    await init(isGlobal, lang);
     return;
   }
 

package/lib/constants.mjs

@@ -62,3 +62,66 @@ Examples: \`[new-feature]\`, \`[bugfix]\`, \`[enhancement]\`, \`[new-work]\`, et
 export function getClaudeMdSection(lang) {
   return lang === 'ko' ? CLAUDE_MD_SECTION_KO : CLAUDE_MD_SECTION_EN;
 }
+
+/**
+ * Bash permissions required by uc-taskmanager agents.
+ * Merged into .claude/settings.local.json during init.
+ *
+ * Categories:
+ *   - File discovery: ls, cat, basename, find, wc, sort, tail, head
+ *   - Pattern matching: grep, sed, cut, tr
+ *   - Formatting: printf, echo
+ *   - Build/Lint: node, npm, bun, yarn, cargo, go, python, ruff, make
+ *   - Git: git add, git commit, git log, git rev-parse
+ *   - Network: curl (callback)
+ */
+export const REQUIRED_PERMISSIONS = [
+  // File read/write tools (project-root scoped)
+  'Read(/**)',
+  'Edit(/**)',
+  'Write(/**)',
+  'Read(**)',
+  'Edit(**)',
+  'Write(**)',
+
+  // File discovery & text utilities
+  'Bash(ls:*)',
+  'Bash(cat:*)',
+  'Bash(mkdir:*)',
+  'Bash(basename:*)',
+  'Bash(find:*)',
+  'Bash(wc:*)',
+  'Bash(sort:*)',
+  'Bash(tail:*)',
+  'Bash(head:*)',
+  'Bash(echo:*)',
+  'Bash(printf:*)',
+
+  // Pattern matching & text processing
+  'Bash(grep:*)',
+  'Bash(sed:*)',
+  'Bash(cut:*)',
+  'Bash(tr:*)',
+
+  // Build & Lint (auto-detect per project type)
+  'Bash(node:*)',
+  'Bash(npm run:*)',
+  'Bash(npm test:*)',
+  'Bash(bun run:*)',
+  'Bash(yarn:*)',
+  'Bash(cargo:*)',
+  'Bash(go build:*)',
+  'Bash(go test:*)',
+  'Bash(python:*)',
+  'Bash(ruff:*)',
+  'Bash(make:*)',
+
+  // Git operations (committer)
+  'Bash(git add:*)',
+  'Bash(git commit:*)',
+  'Bash(git log:*)',
+  'Bash(git rev-parse:*)',
+
+  // Network (callback transmission)
+  'Bash(curl:*)',
+];

package/lib/init.mjs

@@ -2,12 +2,15 @@ import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { AGENT_FILES, getAgentsSrcDir, getClaudeMdSection } from './constants.mjs';
+import { AGENT_FILES, getAgentsSrcDir, getClaudeMdSection, REQUIRED_PERMISSIONS } from './constants.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+import { createInterface } from 'node:readline';
+
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 
 function copyAgents(destDir, lang) {
   const srcDir = getAgentsSrcDir(lang);
@@ -56,7 +59,54 @@ function updateClaudeMd(projectDir, lang) {
   return true;
 }
 
-export function init(isGlobal, lang) {
+function mergePermissions(projectDir) {
+  const settingsPath = join(projectDir, '.claude', 'settings.local.json');
+  let settings = {};
+
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.permissions) settings.permissions = {};
+  if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+
+  const existing = new Set(settings.permissions.allow);
+  let added = 0;
+
+  for (const perm of REQUIRED_PERMISSIONS) {
+    if (!existing.has(perm)) {
+      settings.permissions.allow.push(perm);
+      added++;
+    }
+  }
+
+  if (added > 0) {
+    const dir = dirname(settingsPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  return { added, total: settings.permissions.allow.length };
+}
+
+async function promptPermissions() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    console.log(`\n  ${yellow('?')} Auto-configure Bash permissions for agents? (recommended)`);
+    console.log(`    ${dim('Adds required permissions to .claude/settings.local.json')}`);
+    rl.question('    [Y/n] ', (answer) => {
+      rl.close();
+      const choice = answer.trim().toLowerCase();
+      resolve(choice === '' || choice === 'y' || choice === 'yes');
+    });
+  });
+}
+
+export async function init(isGlobal, lang) {
   const exampleTag = lang === 'ko'
     ? `[추가기능] Add a hello world feature`
     : `[new-feature] Add a hello world feature`;
@@ -98,6 +148,18 @@ export function init(isGlobal, lang) {
     console.log(`    ${dim('-')} works/ directory already exists`);
   }
 
+  const wantPermissions = await promptPermissions();
+  if (wantPermissions) {
+    const { added, total } = mergePermissions(projectDir);
+    if (added > 0) {
+      console.log(`    ${green('✓')} ${added} permissions added to .claude/settings.local.json (total: ${total})`);
+    } else {
+      console.log(`    ${dim('-')} All permissions already configured (${total})`);
+    }
+  } else {
+    console.log(`    ${dim('-')} Skipped permission setup`);
+  }
+
   console.log(`\n  ${dim('Next steps:')}`);
   console.log(`    1. Run ${dim("'claude'")} to start Claude Code`);
   console.log(`    2. Type: ${dim(exampleTag)}\n`);