Writer Agent

Transform documents and URLs into styled article series.

Quick Reference

DP = Direct Path | T1-T3 = Tier 1-3 | ✓ = Load | - = Skip

Tier Workflow Files (loaded at Step 2.7 after tier determination):

Dimension files (loaded at Step 2): voices/{voice}.md, structures/{structure}.md, identities/{identity}.md, audiences/{audience}.md, emotional_maps/{emotion}.md

Workflow Overview

Direct Path (<20K words OR <50K words with <=3 articles):

Main agent writes all articles directly without subagents.

Input → Convert → Style/Structure → Plan → Write(main) → Synthesize → Verify
  1        1           2               3        4            5           6

Standard (Tier 1-2, 20K-100K words):

Input → Convert → Style/Structure → Analyze → Extract → Write → Synthesize → Verify
  1        1           2               3         3         4        5           6

Fast Path (Tier 3, >=100K words):

Input → Convert → Style/Structure → Plan → Write(parallel) → Synthesize → Verify
  1        1           2              3          4              5           6

Step 0: Resolve Skill Paths (BẮT BUỘC)

PHẢI thực hiện TRƯỚC mọi bước khác.

Bước 1: Tìm và chạy wa-env script:

# 1a. Glob thư mục thường (nhanh nhất)
Glob("**/writer-agent/scripts/wa-env")

# 1b. Nếu 1a không có → tìm trong dotdirs (plugin install vào .agents/)
Glob(".agent*/**/wa-env")
Glob(".claude/**/wa-env")

# 1c. Fallback: find (tìm cả dotdir)
Bash: find . -path "*/writer-agent/scripts/wa-env" -not -path "*/.venv/*" 2>/dev/null | head -1

Bước 2: Chạy wa-env để lấy tất cả paths:

# QUAN TRỌNG: Dùng `bash` thay vì `source` để BASH_SOURCE resolve đúng
bash {path_to_wa-env}
# Output: SCRIPTS_DIR, SKILL_DIR, VOICES_DIR, STRUCTURES_DIR,
#         IDENTITIES_DIR, AUDIENCES_DIR, EMOTIONS_DIR, TEMPLATES_DIR, REFERENCES_DIR

Bước 3: Verify nhanh — nếu bất kỳ check nào fail → STOP:

assert Glob(f"{SCRIPTS_DIR}/wa-convert")   # Script chính
assert Glob(f"{VOICES_DIR}/*.md")          # Voice files

FAIL CONDITION: Nếu không tìm thấy wa-env → STOP workflow. KHÔNG tự suy đoán paths. QUAN TRỌNG: Tất cả commands sau PHẢI dùng đường dẫn tuyệt đối từ wa-env.

Step 1: Input Handling

GUARD: SCRIPTS_DIR đã resolve từ Step 0. Nếu chưa → STOP, quay lại Step 0.

Detect input type and convert to markdown.

Output language: Luôn là tiếng Việt, bất kể source language.

File/URL Conversion

{SCRIPTS_DIR}/wa-convert [/path/to/file.pdf or url]

Output: docs/generated/{slug}-{timestamp}/input-handling/content.md

Plain Text Processing

1. Read content (if file)
2. Rewrite to structured markdown (add headings, preserve content)
3. Propose title
4. Execute:

echo "{rewritten_content}" | {SCRIPTS_DIR}/wa-paste-text - --title "{title}"

Error Handling

Step 2: Select Writing Dimensions

Hệ thống 5 chiều độc lập. User chọn preset combo hoặc Custom để mix-match tự do.

Preset Combos (Recommended)

Show bảng sau cho user, hỏi chọn preset hoặc "Custom":

Cách dùng: Hiển thị bảng trên → Hỏi user gõ tên preset (e.g. "Educator") hoặc "Custom".

• Nếu chọn preset: Tất cả 5 dimensions đã set, skip đến Step 2.5
• Nếu chọn Custom: Chuyển sang Step 2a-2f bên dưới (chọn từng chiều)
• Adaptive structure: Dùng khi content mixed/không fit structures cố định. Chỉ available qua Custom mode hoặc user yêu cầu trực tiếp.

Step 2a-2f: Custom Mode (chọn từng chiều)

Flow: Voice → Structure → Identity → Audience → Emotion (tất cả bắt buộc)

Mỗi chiều có default mapping dựa trên voice. Suggest defaults, user PHẢI confirm hoặc chọn khác.

Step 2a: Voice — Hỏi user confirm voice (giọng văn, tone, persona).

Voice files: voices/{voice}.md. Xem references/dimension-comparison.md để so sánh.

Step 2b: Structure — Hỏi user confirm structure. Mỗi voice có default_structure trong frontmatter.

Structure files: structures/{structure}.md

Step 2c: Identity — Hỏi user chọn writer identity.

Step 2d: Audience — Hỏi user viết cho ai.

Step 2e: Emotion — Hỏi user muốn người đọc cảm thấy gì.

Step 2f: Compatibility Check (Custom mode only)

Sau khi chọn xong 5 dimensions, kiểm tra compatibility:

pairs_to_check = [(identity, voice), (audience, voice), (emotion, voice)]
low_compat = [pair for pair in pairs_to_check if compatibility(pair) == "★"]
if low_compat:
    warn(f"Combo {low_compat} có compatibility thấp (★)")
    # Hỏi user: tiếp tục hay chọn khác?

Conflict Resolution: Voice quyết định HOW (style/tone), Profile (Identity/Audience/Emotion) bổ sung WHAT (authority, đối tượng, cảm xúc).

Step 2.5: Select Detail Level

Hỏi user để confirm output detail level.

Default: Standard (if user skips or unclear)

Calculate Target Words (Tham khảo)

LƯU Ý: Target words chỉ mang tính tham khảo. PASS/FAIL dựa trên section coverage, không phải word count.

target_ratio = midpoint of selected level
total_target = source_words × target_ratio

Per article (reference only):
article_target = (article_source_words / source_words) × total_target

Understanding Detail Level Parameters

Two complementary concepts:

1. **target_ratio**: Controls total article length relative to source

• Standard level: 30-40% (midpoint 35%)

2. **example_percentage**: Controls retention of examples within kept content

• Standard level: 60% of examples

See detail-levels.md for worked examples and full specification.

Step 2.6: Tier Reference Table

Canonical tier definitions (referenced throughout documentation):

Priority rules:

• Direct Path conditions are checked FIRST and override tier boundaries
• Documents 20K-50K with ≤3 articles use Direct Path (not Tier 1)
• Only documents failing Direct Path conditions fall through to tier selection

Note: Direct Path <50K condition is further limited by language: EN ~44K, VI ~32K, mixed ~38K words. These limits are pre-computed in structure.json → direct_path.capacity_ok. If capacity exceeded, fallback to Tier 1.

Key differences:

• Direct Path: Main agent handles everything (no subagents)
• Tier 1: Lightweight subagents, read source via line ranges
• Tier 2: Context extraction for compression (only tier with separate glossary file)
• Tier 3: Like Tier 1 but larger chunks, more selective glossary, lower concurrency

Step 2.7: Load Tier Workflow (BẮT BUỘC)

Sau khi xác định tier từ Step 2.6, đọc file workflow tương ứng:

tier = determine_tier(structure_json)  # Từ structure.json

if tier == "direct_path":
    Read(f"{SKILL_DIR}/references/tier-direct-path.md")
elif tier == 1:
    Read(f"{SKILL_DIR}/references/tier-1-workflow.md")
elif tier == 2:
    Read(f"{SKILL_DIR}/references/tier-2-workflow.md")
elif tier == 3:
    Read(f"{SKILL_DIR}/references/tier-3-workflow.md")

Tier workflow file chứa Steps 3-4. Sau khi hoàn thành Step 4, load references/steps-5-6-synthesize-verify.md cho Steps 5-6.

FAIL CONDITION: Nếu không load tier workflow file → KHÔNG biết cách xử lý Steps 3-4 cho tier đó. STOP và load file đúng.

Cài đặt thư viện mới

Skill sử dụng virtual environment tại {SCRIPTS_DIR}/.venv. Khi cần cài thêm thư viện, PHẢI activate venv trước:

# 1. Activate venv (dùng SCRIPTS_DIR từ Step 0)
source {SCRIPTS_DIR}/.venv/bin/activate

# 2. Cài package
uv pip install <package>

# 3. Cập nhật requirements.txt
uv pip freeze > {SCRIPTS_DIR}/requirements.txt

KHÔNG dùng:

• uv pip install <package> khi chưa activate venv → lỗi "No virtual environment found"
• uv pip install <package> --system → lỗi "externally managed" (Python Homebrew)
• uv add <package> → cần pyproject.toml, skill dùng requirements.txt