writer-agent

Writer Agent

Transform documents and URLs into styled article series.

Quick Reference

Reference	Purpose	Load at Step	DP	T1	T2	T3
directory-structure.md	Output folder layout	Step 1	✓	✓	✓	✓
dimension-selection.md	Custom mode dimension tables	Step 2 (Custom)	✓	✓	✓	✓
decision-trees.md	Workflow decision guides	On confusion only	✓	✓	✓	✓
retry-workflow.md	Error recovery procedures	On error only	-	✓	✓	✓
large-doc-processing.md	Handling documents >50K words	Step 3 (if >20K)	-	-	✓	✓
article-writer-prompt.md	Subagent prompt templates	Step 4	-	✓	✓	✓
context-extractor-prompt.md	Context extraction template	Step 3 (Tier 2)	-	-	✓	-
context-optimization.md	Context optimization anti-patterns	Step 3.1	-	✓	✓	✓
detail-levels.md	Output detail level options	Step 2.5	✓	✓	✓	✓
shared-article-writing.md	Shared Steps 4.0-4.6	Step 4	-	✓	✓	✓

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

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

Tier	File	When
Direct Path	tier-direct-path.md	<20K OR (<50K AND ≤3 articles)
Tier 1	tier-1-workflow.md	20K-50K (fails Direct Path)
Tier 2	tier-2-workflow.md	50K-100K
Tier 3	tier-3-workflow.md	>=100K

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)

Tìm wa-env → chạy → dùng paths tuyệt đối cho toàn bộ workflow.

# Tìm wa-env (thử Glob trước, fallback find nếu plugin installed vào dotdir)
Glob("**/writer-agent/scripts/wa-env")  # hoặc Glob(".claude/**/wa-env")

# Chạy (dùng bash, không dùng source — để BASH_SOURCE resolve đúng)
bash {path_to_wa-env}
# → SCRIPTS_DIR, SKILL_DIR, VOICES_DIR, STRUCTURES_DIR, IDENTITIES_DIR,
#   AUDIENCES_DIR, EMOTIONS_DIR, TEMPLATES_DIR, REFERENCES_DIR

# Verify
assert Glob(f"{SCRIPTS_DIR}/wa-convert") and Glob(f"{VOICES_DIR}/*.md")

FAIL CONDITION: Không tìm thấy wa-env → STOP. KHÔNG tự suy đoán paths.

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.

Input Type	Detection	Action
File (PDF/DOCX/EPUB/etc)	Path + extension	wa-convert {path}
URL (web page)	http:// or https://	wa-convert {url}
YouTube URL	youtube.com or youtu.be	wa-convert {url}
Plain text / .txt / .md	No complex extension	Rewrite → wa-paste-text

File/URL Conversion

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

Output: writer-agent/{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

Error	Action
File not found	Ask for correct path
Unsupported format	Try Docling, confirm with user
URL fetch failed	Report and stop
Empty content	Warn, confirm before continue
Encrypted PDF	Ask for decrypted version

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":

Preset	Voice	Structure	Identity	Audience	Emotion
Educator	Teacher	Building Blocks	Tech Builder	Curious Beginners	Empower & Challenge
Storyteller	Storyteller	Story Arc	Contemplative Thinker	Deep Seekers	Reflect & Discover
Analyst	Objective	BLUF-Evidence	Knowledge Curator	Busy Professionals	Empower & Challenge
Explorer	Investigator	Five Layers	Knowledge Curator	Deep Seekers	Provoke & Transform
Mentor	Guide	Depth-Practice	Contemplative Thinker	Curious Beginners	Reflect & Discover
Reflector	Personal	Spiral Return	Contemplative Thinker	Deep Seekers	Reflect & Discover
Zen Master	Dialogue	Master-Student	Contemplative Thinker	Deep Seekers	Reflect & Discover

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.

Custom Mode

Khi user chọn "Custom" → đọc dimension-selection.md để chọn từng chiều (Voice → Structure → Identity → Audience → Emotion) kèm compatibility check.

Step 2.5: Select Detail Level

Hỏi user để confirm output detail level.

Level	Ratio	Description
Concise	15-25%	Tóm lược, giữ ý chính
Standard	30-40%	Cân bằng (Recommended)
Comprehensive	50-65%	Chi tiết, giữ nhiều ví dụ
Faithful	75-90%	Gần như đầy đủ, viết lại theo style

Default: Standard (if user skips or unclear). PASS/FAIL dựa trên section coverage, không phải word count.

Chi tiết calculation (target_ratio, example_percentage) và worked examples → detail-levels.md.

Step 2.6: Tier Reference Table

Canonical tier definitions (referenced throughout documentation):

Tier	Word Count	Strategy	Context Approach	Glossary	max_concurrent
Direct Path	<20K OR (<50K AND ≤3 articles)	Main agent writes all	N/A (no subagents)	Inline (~200 words)	N/A
Tier 1	20K-50K (fails Direct Path)	Subagents read source directly	No context files	Inline (~200 words)	3
Tier 2	50K-100K	Smart compression	Context extractors	Separate file (~600 words)	3
Tier 3	>=100K	Fast Path, minimal overhead	No context files	Inline (~300 words)	2

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.