devlyn-cli 0.5.2 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/bin/devlyn.js +1 -0
  2. package/config/commands/devlyn.team-resolve.md +31 -2
  3. package/optional-skills/dokkit/ANALYSIS.md +198 -0
  4. package/optional-skills/dokkit/COMMANDS.md +365 -0
  5. package/optional-skills/dokkit/DOCX-XML.md +76 -0
  6. package/optional-skills/dokkit/EXPORT.md +102 -0
  7. package/optional-skills/dokkit/FILLING.md +377 -0
  8. package/optional-skills/dokkit/HWPX-XML.md +73 -0
  9. package/optional-skills/dokkit/IMAGE-SOURCING.md +127 -0
  10. package/optional-skills/dokkit/INGESTION.md +65 -0
  11. package/optional-skills/dokkit/SKILL.md +153 -0
  12. package/optional-skills/dokkit/STATE.md +60 -0
  13. package/optional-skills/dokkit/references/docx-field-patterns.md +151 -0
  14. package/optional-skills/dokkit/references/docx-structure.md +58 -0
  15. package/optional-skills/dokkit/references/field-detection-patterns.md +130 -0
  16. package/optional-skills/dokkit/references/hwpx-field-patterns.md +461 -0
  17. package/optional-skills/dokkit/references/hwpx-structure.md +159 -0
  18. package/optional-skills/dokkit/references/image-opportunity-heuristics.md +121 -0
  19. package/optional-skills/dokkit/references/image-xml-patterns.md +338 -0
  20. package/optional-skills/dokkit/references/section-image-interleaving.md +346 -0
  21. package/optional-skills/dokkit/references/section-range-detection.md +118 -0
  22. package/optional-skills/dokkit/references/state-schema.md +143 -0
  23. package/optional-skills/dokkit/references/supported-formats.md +67 -0
  24. package/optional-skills/dokkit/scripts/compile_hwpx.py +134 -0
  25. package/optional-skills/dokkit/scripts/detect_fields.py +301 -0
  26. package/optional-skills/dokkit/scripts/detect_fields_hwpx.py +286 -0
  27. package/optional-skills/dokkit/scripts/export_pdf.py +99 -0
  28. package/optional-skills/dokkit/scripts/parse_hwpx.py +185 -0
  29. package/optional-skills/dokkit/scripts/parse_image_with_gemini.py +159 -0
  30. package/optional-skills/dokkit/scripts/parse_xlsx.py +98 -0
  31. package/optional-skills/dokkit/scripts/source_images.py +365 -0
  32. package/optional-skills/dokkit/scripts/validate_docx.py +142 -0
  33. package/optional-skills/dokkit/scripts/validate_hwpx.py +281 -0
  34. package/optional-skills/dokkit/scripts/validate_state.py +132 -0
  35. package/package.json +1 -1
package/bin/devlyn.js CHANGED
@@ -70,6 +70,7 @@ const OPTIONAL_ADDONS = [
70
70
  { name: 'prompt-engineering', desc: 'Claude 4 prompt optimization using Anthropic best practices', type: 'local' },
71
71
  { name: 'better-auth-setup', desc: 'Production-ready Better Auth + Hono + Drizzle + PostgreSQL auth setup', type: 'local' },
72
72
  { name: 'pyx-scan', desc: 'Check whether an AI agent skill is safe before installing', type: 'local' },
73
+ { name: 'dokkit', desc: 'Document template filling for DOCX/HWPX — ingest, fill, review, export', type: 'local' },
73
74
  // Local optional commands (copied to .claude/commands/)
74
75
  { name: 'devlyn.pencil-sync', desc: 'Sync designs between codebase and Pencil (.pen files) via MCP', type: 'command' },
75
76
  // External skill packs (installed via npx skills add)
@@ -6,6 +6,22 @@ $ARGUMENTS
6
6
 
7
7
  <team_workflow>
8
8
 
9
+ <code_quality_standards>
10
+ Every line of code produced by this team must be **production-grade**. This is not a prototype — treat every fix and feature as code that ships to real users at scale.
11
+
12
+ **Non-negotiable standards**:
13
+ - **Root cause fixes only** — never workarounds, never "good enough for now" (see `<no_workarounds>` below)
14
+ - **Graceful error handling** — errors are caught, surfaced to the user with actionable context, and logged. No silent swallowing. No raw stack traces in UI. Every failure path has a recovery or clear error state.
15
+ - **Robust edge case coverage** — handle nulls, empty states, concurrent access, network failures, partial data, and boundary conditions. If it can happen in production, handle it.
16
+ - **Optimized for performance** — no unnecessary re-renders, no N+1 queries, no unbounded loops, no blocking I/O on hot paths. Profile before and after when touching performance-sensitive code.
17
+ - **Scalable patterns** — solutions must work at 10x the current load. Avoid patterns that degrade with data size (O(n²) where O(n) is possible, in-memory aggregation of unbounded datasets, missing pagination).
18
+ - **Best practice adherence** — follow the language/framework idioms of the codebase. Use established patterns over novel approaches. Leverage the type system. Prefer composition over inheritance. Keep functions focused and testable.
19
+ - **Clean interfaces** — clear contracts between modules. No leaky abstractions. Inputs validated at boundaries. Return types are explicit, not `any`.
20
+ - **Defensive but not paranoid** — validate external inputs rigorously, trust internal interfaces. Don't add guards for impossible states — instead, make impossible states unrepresentable through types.
21
+
22
+ Every teammate should evaluate their findings and recommendations against these standards. The Team Lead enforces them during synthesis and implementation.
23
+ </code_quality_standards>
24
+
9
25
  ## Phase 1: INTAKE (You are the Team Lead — work solo first)
10
26
 
11
27
  Before spawning any teammates, do your own investigation:
@@ -487,8 +503,15 @@ Implementation order:
487
503
  3. Incorporate security constraints from the Security Auditor (if present)
488
504
  4. Respect architectural patterns flagged by the Architecture Reviewer (if present)
489
505
  5. Apply UX requirements from the UX Designer and Accessibility Auditor (if present)
490
- 6. Run the failing test if it still fails, revert and re-analyze (never layer fixes)
491
- 7. Run the full test suite for regressions
506
+ 6. **Quality gate**before running tests, review your own code against `<code_quality_standards>`:
507
+ - Is error handling graceful and user-facing (not silent, not raw)?
508
+ - Are edge cases handled (nulls, empty, concurrent, partial data)?
509
+ - Is the solution performant at scale (no O(n²), no unbounded loops)?
510
+ - Does the code follow existing codebase patterns and idioms?
511
+ - Are interfaces clean and types explicit (no `any`, no leaky abstractions)?
512
+ - If any check fails, refactor BEFORE proceeding to tests
513
+ 7. Run the failing test — if it still fails, revert and re-analyze (never layer fixes)
514
+ 8. Run the full test suite for regressions
492
515
 
493
516
  ## Phase 6: CLEANUP
494
517
 
@@ -531,6 +554,12 @@ Present findings in this format:
531
554
  ### Verification
532
555
  - [ ] Failing test now passes
533
556
  - [ ] No regressions in full test suite
557
+ - [ ] Root cause addressed (no workarounds — see `<no_workarounds>` criteria)
558
+ - [ ] Error handling is graceful with user-facing messages
559
+ - [ ] Edge cases covered (nulls, empty states, boundaries, concurrent access)
560
+ - [ ] Performance verified (no O(n²), no N+1, no unbounded operations)
561
+ - [ ] Code follows existing codebase patterns and idioms
562
+ - [ ] Types are explicit, interfaces are clean, no `any` leaks
534
563
  - [ ] UX/accessibility concerns addressed (if applicable)
535
564
  - [ ] Manual verification (if applicable)
536
565
 
@@ -0,0 +1,198 @@
1
+ # Analysis Knowledge
2
+
3
+ Template analysis patterns and field detection strategies for the dokkit-analyzer agent. Covers field identification, confidence scoring, and the analysis output schema.
4
+
5
+ ## Table of Contents
6
+
7
+ - [Field Detection Strategy](#field-detection-strategy)
8
+ - [Section Detection](#section-detection)
9
+ - [Cross-Language Mapping](#cross-language-mapping)
10
+ - [Confidence Scoring](#confidence-scoring)
11
+ - [Analysis Output Format](#analysis-output-format)
12
+
13
+ ---
14
+
15
+ ## Field Detection Strategy
16
+
17
+ Detect ALL fillable locations in a template. Fields appear in these patterns:
18
+
19
+ ### 1. Placeholder Text
20
+ - `{{field_name}}` or `<<field_name>>` — explicit placeholders
21
+ - `[field_name]` or `(field_name)` — bracket patterns
22
+ - `___` (underscores) — blank line indicators
23
+ - `...` (dots) — fill-in indicators
24
+
25
+ ### 2. Empty Table Cells
26
+ In form-like documents (especially Korean templates):
27
+ - A label cell (e.g., "Name") with an adjacent empty cell = fill target
28
+ - Pattern: `[Label Cell] [Empty Cell]`
29
+
30
+ ### 3. Instruction Text
31
+ Text telling the user what to enter:
32
+ - "(enter name here)", "(type your answer)"
33
+ - Korean: "(날짜를 입력하세요)", "(내용을 기재)"
34
+ - These should be REPLACED with the actual value
35
+
36
+ ### 4. Form Controls (DOCX only)
37
+ - Content controls (`w:sdt`) with explicit placeholder values
38
+ - Legacy form fields (`w:fldChar`)
39
+
40
+ ### 5. Underline Runs
41
+ Runs styled with underline containing only spaces or underscores:
42
+ - Indicates a blank line for handwriting
43
+ - In digital filling, replace with the value
44
+
45
+ ### 6. Image Fields
46
+ Fields requiring an image rather than text:
47
+ - `{{사진}}`, `{{photo}}`, `<<signature>>` — image placeholder text
48
+ - Existing `<w:drawing>` (DOCX) or `<hp:pic>` (HWPX) in table cells
49
+ - Empty cells adjacent to cells with image keywords
50
+
51
+ **Image keywords** (Korean): 사진, 증명사진, 여권사진, 로고, 서명, 날인, 도장, 직인
52
+ **Image keywords** (English): Photo, Picture, Logo, Signature, Stamp, Seal, Image, Portrait
53
+
54
+ **Classification** (`image_type`): `photo`, `logo`, `signature`, or `figure`
55
+
56
+ ### 7. Writing Tip Boxes (작성 팁)
57
+ Standalone 1x1 tables with DASH borders containing guidance text:
58
+ - HWPX: `rowCnt="1"`, `colCnt="1"` with `※` text
59
+ - DOCX: Single `<w:tr>/<w:tc>` with dashed borders
60
+ - Often styled in red (#FF0000)
61
+
62
+ Detect as `field_type: "tip_box"` with `action: "delete"`.
63
+
64
+ **Container types**:
65
+ - `"standalone"` — top-level 1x1 table between other content
66
+ - `"nested"` — inside `<hp:subList>` within a fill-target cell; include `parent_field_id`
67
+
68
+ **`has_formatting` flag**: For mapped fields where `mapped_value` is >100 chars and contains markdown syntax (`**bold**`, `## heading`, `- bullet`, `1. numbered`), set `has_formatting: true`.
69
+
70
+ ## Section Detection
71
+
72
+ Group fields into logical sections:
73
+ 1. Use document headings (H1, H2) as section boundaries
74
+ 2. In table-based forms, use spanning header rows
75
+ 3. In Korean templates, look for: "인적사항", "학력", "경력", "자격증"
76
+ 4. If no clear sections, use "General" as default
77
+
78
+ ## Cross-Language Mapping
79
+
80
+ Common Korean-English field equivalents:
81
+
82
+ | Korean | English |
83
+ |--------|---------|
84
+ | 성명 / 이름 | Name / Full Name |
85
+ | 생년월일 | Date of Birth |
86
+ | 주소 | Address |
87
+ | 전화번호 / 연락처 | Phone / Contact |
88
+ | 이메일 | Email |
89
+ | 학력 | Education |
90
+ | 경력 | Work Experience |
91
+ | 자격증 | Certifications |
92
+ | 직위 / 직책 | Position / Title |
93
+ | 회사명 | Company Name |
94
+ | 기간 | Period / Duration |
95
+
96
+ ## Confidence Scoring
97
+
98
+ ### High Confidence
99
+ - Exact label match between source and template field
100
+ - Unambiguous data (one clear value in sources)
101
+ - Same language label match
102
+
103
+ ### Medium Confidence
104
+ - Semantic match (different wording, same meaning)
105
+ - Cross-language match (Korean-English)
106
+ - Multiple candidate values in sources
107
+ - Partial data match
108
+
109
+ ### Low Confidence
110
+ - Indirect inference (value derived from context)
111
+ - Ambiguous mapping (could match multiple fields)
112
+ - Best guess from limited data
113
+
114
+ ## Analysis Output Format
115
+
116
+ Write to `.dokkit/analysis.json`:
117
+
118
+ ```json
119
+ {
120
+ "template": {
121
+ "file_path": "...",
122
+ "file_type": "docx|hwpx",
123
+ "display_name": "..."
124
+ },
125
+ "sections": [
126
+ {
127
+ "name": "Section Name",
128
+ "fields": [
129
+ {
130
+ "id": "field_001",
131
+ "label": "Field Label",
132
+ "field_type": "placeholder_text|empty_cell|underline|form_control|instruction_text|image|tip_box|section_content|table_content",
133
+ "xml_path": {
134
+ "file": "word/document.xml",
135
+ "element_path": "body/tbl[0]/tr[1]/tc[2]/p[0]/r[0]",
136
+ "namespaced_path": "w:body/w:tbl[0]/w:tr[1]/w:tc[2]/w:p[0]/w:r[0]"
137
+ },
138
+ "pattern": "{{name}}",
139
+ "current_content": "{{name}}",
140
+ "mapped_value": "John Doe",
141
+ "source": "resume.pdf",
142
+ "source_location": "key_value_pairs.Name",
143
+ "confidence": "high",
144
+ "has_formatting": false
145
+ },
146
+ {
147
+ "id": "field_015",
148
+ "label": "tip box label",
149
+ "field_type": "tip_box",
150
+ "action": "delete",
151
+ "container": "standalone",
152
+ "xml_path": { "file": "...", "element_path": "...", "namespaced_path": "..." },
153
+ "pattern": "(tip box: 1x1 table)",
154
+ "current_content": "※ 작성 팁: ...",
155
+ "mapped_value": null,
156
+ "confidence": "high"
157
+ },
158
+ {
159
+ "id": "field_020",
160
+ "label": "사진",
161
+ "field_type": "image",
162
+ "image_type": "photo",
163
+ "xml_path": { "file": "...", "element_path": "...", "namespaced_path": "..." },
164
+ "pattern": "(empty cell, image label)",
165
+ "current_content": "",
166
+ "image_source": "ingested",
167
+ "image_file": ".dokkit/sources/photo.jpg",
168
+ "dimensions": { "width_emu": 1260000, "height_emu": 1620000 },
169
+ "confidence": "high"
170
+ }
171
+ ]
172
+ }
173
+ ],
174
+ "summary": {
175
+ "total_fields": 22,
176
+ "mapped": 18,
177
+ "unmapped": 4,
178
+ "high_confidence": 15,
179
+ "medium_confidence": 2,
180
+ "low_confidence": 1,
181
+ "image_fields": 2,
182
+ "image_fields_sourced": 1,
183
+ "image_fields_pending": 1,
184
+ "tip_boxes": 3
185
+ }
186
+ }
187
+ ```
188
+
189
+ ### Critical Rules for Analysis Output
190
+
191
+ - For `table_content` fields that are pre-filled from source: set `mapped_value: null` with `action: "preserve"`. NEVER set `mapped_value` to a placeholder string — the filler treats any non-null `mapped_value` as literal data and will destroy the table.
192
+ - For `image` fields: search `.dokkit/sources/` for matching images first. Set `image_source: "ingested"` if found, or leave `image_file: null` (pending).
193
+ - For `section_content` fields: scan for visual enhancement opportunities (max 3 per field, max 12 total). Record with `generation_prompt`, `dimensions`, `status: "pending"`.
194
+
195
+ ## References
196
+
197
+ See `references/field-detection-patterns.md` for advanced detection heuristics (9 DOCX + 6 HWPX).
198
+ See `references/image-opportunity-heuristics.md` for AI image opportunity detection in section content.
@@ -0,0 +1,365 @@
1
+ # Dokkit Command Reference
2
+
3
+ Complete workflows for all 9 subcommands. Loaded automatically into context when `/dokkit` is invoked.
4
+
5
+ ## Table of Contents
6
+
7
+ - [init](#init) — Initialize workspace
8
+ - [sources](#sources) — Source dashboard
9
+ - [preview](#preview) — PDF preview
10
+ - [ingest](#ingest) — Ingest source documents
11
+ - [fill](#fill) — End-to-end fill pipeline
12
+ - [fill-doc](#fill-doc) — Analyze and fill template
13
+ - [modify](#modify) — Targeted changes
14
+ - [review](#review) — Confidence review
15
+ - [export](#export) — Export to format
16
+
17
+ ---
18
+
19
+ ## init
20
+
21
+ Initialize or reset the `.dokkit/` workspace for a new document filling session.
22
+
23
+ ### Arguments
24
+ - `--force` or `-f`: Skip confirmation and reset without asking
25
+ - `--keep-sources`: Reset template/output but preserve ingested sources
26
+
27
+ ### Procedure
28
+
29
+ 1. Check if `.dokkit/` already exists
30
+ 2. If it exists and `--force` is not passed, ask the user to confirm reset
31
+ 3. If `--keep-sources` is used, preserve `.dokkit/sources/` and source entries in state.json
32
+ 4. Create the workspace structure:
33
+ ```
34
+ .dokkit/
35
+ ├── sources/
36
+ ├── template_work/
37
+ ├── output/
38
+ ├── images/
39
+ └── state.json
40
+ ```
41
+ 5. Initialize `state.json`:
42
+ ```json
43
+ {
44
+ "version": "1.0",
45
+ "created": "<ISO timestamp>",
46
+ "sources": [],
47
+ "template": null,
48
+ "analysis": null,
49
+ "filled_document": null,
50
+ "exports": []
51
+ }
52
+ ```
53
+ 6. Validate the state file
54
+ 7. Report success with next step guidance
55
+
56
+ ### Output
57
+ ```
58
+ Dokkit workspace initialized at .dokkit/
59
+ sources/ — ready for /dokkit ingest
60
+ template_work/ — ready for /dokkit fill
61
+ output/ — ready for /dokkit export
62
+ state.json — initialized
63
+
64
+ Next: Use /dokkit ingest <file> to add source documents.
65
+ ```
66
+
67
+ ### Rules
68
+ - Inline command — do NOT fork to any agent
69
+ - If resetting, warn about data loss unless --force is used
70
+
71
+ ---
72
+
73
+ ## sources
74
+
75
+ Display all ingested source documents with their status, type, and summary.
76
+
77
+ ### Procedure
78
+
79
+ 1. Read `.dokkit/state.json`
80
+ 2. If `.dokkit/` does not exist, show error: "No workspace found. Run `/dokkit init` first."
81
+ 3. If no sources exist, show empty state with supported formats list
82
+ 4. For each source, display: name, type, status, summary
83
+ 5. Show total count and any errors
84
+
85
+ ### Output
86
+ ```
87
+ Ingested Sources (3 total)
88
+
89
+ # Name Type Status Summary
90
+ 1 resume.pdf PDF ready Personal resume with education and work history
91
+ 2 transcript.xlsx XLSX ready Academic transcript with grades and courses
92
+ 3 scan.png PNG error OCR failed — image too blurry
93
+
94
+ Use /dokkit ingest <file> to add more sources.
95
+ ```
96
+
97
+ ### Rules
98
+ - Inline command — do NOT fork to any agent
99
+ - Read-only: only reads state.json, never modifies anything
100
+
101
+ ---
102
+
103
+ ## preview
104
+
105
+ Generate a visual preview of the current filled document as PDF.
106
+
107
+ ### Procedure
108
+
109
+ 1. Read `.dokkit/state.json` to check document status
110
+ 2. If no filled document exists, show error: "No filled document. Run `/dokkit fill <template>` first."
111
+ 3. Compile the current `template_work/` into a temporary file
112
+ 4. Convert to PDF using LibreOffice: `soffice --headless --convert-to pdf --outdir .dokkit/output/ <file>`
113
+ 5. Report the preview file path
114
+
115
+ ### Output
116
+ ```
117
+ Preview generated: .dokkit/output/preview_<name>.pdf
118
+ Open this file to see how the filled document looks.
119
+ ```
120
+
121
+ ### Rules
122
+ - Inline command — do NOT fork to any agent
123
+ - If LibreOffice is not available, show error with install guidance
124
+ - Preview is temporary — `/dokkit export` creates the final output
125
+
126
+ ---
127
+
128
+ ## ingest
129
+
130
+ Parse one or more source documents and add them to the workspace for template filling.
131
+
132
+ ### Arguments
133
+ One or more file paths (space-separated or comma-separated).
134
+
135
+ <example>
136
+ `/dokkit ingest docs/resume.pdf`
137
+ `/dokkit ingest docs/resume.pdf docs/financials.xlsx docs/photo.jpg`
138
+ </example>
139
+
140
+ ### Procedure
141
+
142
+ 1. Parse remaining arguments to extract file paths
143
+ 2. Validate each file path exists. Show error for missing files, continue with valid ones.
144
+ 3. **Auto-initialize workspace**: If `.dokkit/` does not exist, create it with initial state.json. Report: "Workspace initialized at .dokkit/"
145
+ 4. **Ingest each file** sequentially by spawning the **dokkit-ingestor** agent:
146
+ - Pass the file path as context
147
+ - The agent parses the file, writes to `.dokkit/sources/`, updates `state.json`
148
+ - Report progress: "Ingested 1/3: resume.pdf (ready)"
149
+ 5. **Show sources dashboard** after all files complete
150
+
151
+ ### Delegation
152
+ For each file, spawn the dokkit-ingestor agent:
153
+ > "Ingest the source document at `<file_path>`. Follow the dokkit-ingestor agent instructions. The workspace is at `.dokkit/`."
154
+
155
+ ### Rules
156
+ - Auto-initialize workspace if `.dokkit/` does not exist — do NOT tell user to run `/dokkit init`
157
+ - Supported formats: PDF, DOCX, XLSX, CSV, PPTX, HWPX, PNG, JPG, TXT, MD, JSON, HTML
158
+ - If a format is unsupported, show error with supported formats list and skip that file
159
+ - If no valid files are provided, show error with usage example
160
+ - Always show sources dashboard after ingestion completes
161
+
162
+ ---
163
+
164
+ ## fill
165
+
166
+ Fully automated document filling pipeline: analyze, fill, review, auto-fix, and export in one step.
167
+
168
+ ### Arguments
169
+ File path to the template document (DOCX or HWPX).
170
+
171
+ <example>
172
+ `/dokkit fill docs/template.hwpx`
173
+ `/dokkit fill form.docx`
174
+ </example>
175
+
176
+ ### Procedure
177
+
178
+ **Phase 1 — Validate**:
179
+ 1. Validate the template exists and is DOCX or HWPX
180
+ 2. Check `.dokkit/` workspace exists — if not, show error: "No workspace found. Run `/dokkit ingest <files>` first."
181
+ 3. Check at least one source has status "ready" — if not, show error: "No sources ingested."
182
+ 4. Report: "Starting fill pipeline with N sources -> template_name"
183
+
184
+ **Phase 2 — Analyze**:
185
+ 5. Spawn the **dokkit-analyzer** agent to detect fields, map to sources, write `analysis.json`
186
+ 6. Report: "Found N fields (X mapped, Y unmapped, Z images)"
187
+
188
+ **Phase 3 — Source Images**:
189
+ 7. **Cell-level images**: For each `field_type: "image"` with `image_file: null` and `image_type: "figure"`:
190
+ - Run: `python scripts/source_images.py generate --prompt "<prompt>" --preset technical_illustration --output-dir .dokkit/images/ --project-dir . --lang ko`
191
+ - Parse `__RESULT__` JSON, update `analysis.json`
192
+ - Skip photo/signature types (require user-provided files)
193
+ - Default `--lang ko` (Korean only). Override with user instruction if needed.
194
+ 8. **Section content images**: For each `image_opportunities` entry with `status: "pending"`:
195
+ - Run: `python scripts/source_images.py generate --prompt "<generation_prompt>" --preset <preset> --output-dir .dokkit/images/ --project-dir . --lang ko`
196
+ - On failure: set `status: "skipped"`, log reason
197
+ - Use `--lang ko+en` if the content contains technical terms that benefit from English (e.g., architecture diagrams with API names).
198
+ 9. Report: "Sourced X/Y images"
199
+
200
+ **Phase 4 — Fill**:
201
+ 10. Spawn the **dokkit-filler** agent in fill mode
202
+
203
+ **Phase 5 — Review and Auto-Fix Loop**:
204
+ 11. Evaluate fill result: count fields by confidence, identify fixable issues
205
+ 12. **Auto-fix**: For fixable issues, spawn **dokkit-filler** in modify mode
206
+ - Re-map low-confidence fields where better data exists
207
+ - Fix formatting issues (date formats, truncated text)
208
+ - Do NOT auto-fix: unfilled fields, image fields without sources
209
+ 13. If auto-fix made changes, re-evaluate. Maximum 2 iterations.
210
+ 14. Present **final review** table (section-by-section with confidence)
211
+
212
+ **Phase 6 — Export**:
213
+ 15. Export in same format as input template via **dokkit-exporter** agent
214
+ 16. Report output path and file size
215
+
216
+ **Phase 7 — Next Steps**:
217
+ 17. Offer: `/dokkit modify "..."`, `/dokkit export pdf`, `/dokkit review`
218
+
219
+ ### Delegation
220
+
221
+ **Agent 1 — Analyzer** (dokkit-analyzer):
222
+ > "Analyze the template at `<path>`. Detect all fillable fields INCLUDING image fields. Map to sources. Write `analysis.json`."
223
+
224
+ **Agent 2 — Filler** (dokkit-filler, fill mode):
225
+ > "Fill the template using `analysis.json`. Mode: fill. Insert images where `image_file` is populated. Interleave section content images at anchor points."
226
+
227
+ **Agent 2b — Filler** (dokkit-filler, modify mode — auto-fix, if needed):
228
+ > "Modify the filled document. Mode: modify. Fix: `<list of issues>`."
229
+
230
+ **Agent 3 — Exporter** (dokkit-exporter):
231
+ > "Export the filled document. Format: `<format>`. Compile from `.dokkit/template_work/` and save to `.dokkit/output/`."
232
+
233
+ ### Rules
234
+ - At least one source must be ingested before filling
235
+ - Auto-fix loop runs maximum 2 iterations
236
+ - Auto-fix does NOT fill fields with missing source data
237
+ - Always show the full review table before exporting
238
+ - If any phase fails, show the error and stop — do NOT proceed
239
+
240
+ ---
241
+
242
+ ## fill-doc
243
+
244
+ Analyze a template and fill its fields using ingested source data. Does NOT auto-fix or export.
245
+
246
+ ### Arguments
247
+ File path to the template document (DOCX or HWPX).
248
+
249
+ <example>
250
+ `/dokkit fill-doc docs/template.docx`
251
+ </example>
252
+
253
+ ### Procedure
254
+
255
+ 1. Validate the template exists and is DOCX or HWPX
256
+ 2. Check `.dokkit/` workspace exists with at least one ready source
257
+ 3. **Analyze**: Spawn the **dokkit-analyzer** agent
258
+ 4. **Source Images**: Same as `/dokkit fill` Phase 3 (cell-level + section content)
259
+ 5. **Fill**: Spawn the **dokkit-filler** agent in fill mode
260
+ 6. Present review summary
261
+
262
+ ### Delegation
263
+
264
+ **First**: Spawn the dokkit-analyzer agent:
265
+ > "Analyze the template at `<path>`. Detect all fillable fields INCLUDING image fields. Map to sources. Write `analysis.json`."
266
+
267
+ **Image sourcing** (inline, between agents):
268
+ - **Pass A — Cell-level**: For `field_type: "image"` with `image_file: null` and `image_type: "figure"`, run `python scripts/source_images.py generate --prompt "..." --preset ... --output-dir .dokkit/images/ --project-dir . --lang ko`
269
+ - **Pass B — Section content**: For `image_opportunities` with `status: "pending"`, run `python scripts/source_images.py generate --prompt "..." --preset ... --output-dir .dokkit/images/ --project-dir . --lang ko`
270
+ - Default language is `ko` (Korean only). Use `--lang ko+en` for mixed content, or `--lang en` for English-only.
271
+
272
+ **Then**: Spawn the dokkit-filler agent in fill mode:
273
+ > "Fill the template using `analysis.json`. Mode: fill. Insert images where populated. Interleave section content images at anchor points."
274
+
275
+ ### Rules
276
+ - Template must be DOCX or HWPX
277
+ - Analyzer runs FIRST, then filler
278
+ - Original template is never modified
279
+
280
+ ---
281
+
282
+ ## modify
283
+
284
+ Apply targeted changes to the filled document based on natural language instructions.
285
+
286
+ ### Arguments
287
+ A natural language instruction describing the change.
288
+
289
+ <example>
290
+ `/dokkit modify "Change the phone number to 010-1234-5678"`
291
+ `/dokkit modify "Re-do the education section using the transcript"`
292
+ `/dokkit modify "Use YYYY-MM-DD format for all dates"`
293
+ </example>
294
+
295
+ ### Procedure
296
+
297
+ 1. Check `.dokkit/state.json` for an active filled document. If none, show error: "No filled document. Run `/dokkit fill <template>` first."
298
+ 2. Spawn the **dokkit-filler** agent in modify mode
299
+
300
+ ### Delegation
301
+ > "Modify the filled document. Mode: modify. User instruction: `<instruction>`. Read `analysis.json` for field locations and make surgical changes."
302
+
303
+ ### Rules
304
+ - A filled document must exist
305
+ - Only modify targeted fields — do not re-process the entire document
306
+ - Manual overrides get confidence "high"
307
+
308
+ ---
309
+
310
+ ## review
311
+
312
+ Present the filled document for review with section-by-section confidence annotations.
313
+
314
+ ### Arguments
315
+ Optional: section name or action.
316
+
317
+ <example>
318
+ `/dokkit review` — review all sections
319
+ `/dokkit review "Personal Information"` — review specific section
320
+ `/dokkit review approve` — mark document as finalized
321
+ </example>
322
+
323
+ ### Procedure
324
+
325
+ 1. Check `.dokkit/state.json` for an active filled document. If none, show error.
326
+ 2. Spawn the **dokkit-filler** agent in review mode
327
+
328
+ ### Delegation
329
+ > "Review the filled document. Mode: review. Read `analysis.json` and present section-by-section review with confidence annotations."
330
+
331
+ If section or action specified:
332
+ > "Focus on section: `<section>` / Action: `<action>`"
333
+
334
+ ### Rules
335
+ - A filled document must exist
336
+ - Review is read-only — shows status but changes nothing
337
+ - "approve" action sets document status to "finalized"
338
+
339
+ ---
340
+
341
+ ## export
342
+
343
+ Compile and export the filled document in the specified format.
344
+
345
+ ### Arguments
346
+ Output format: `docx`, `hwpx`, or `pdf`.
347
+
348
+ <example>
349
+ `/dokkit export docx`
350
+ `/dokkit export pdf`
351
+ </example>
352
+
353
+ ### Procedure
354
+
355
+ 1. Check `.dokkit/state.json` for a filled document. If none, show error.
356
+ 2. Validate the requested format is supported
357
+ 3. Spawn the **dokkit-exporter** agent
358
+
359
+ ### Delegation
360
+ > "Export the filled document. Format: `<format>`. Compile from `.dokkit/template_work/` and save to `.dokkit/output/`."
361
+
362
+ ### Rules
363
+ - Supported formats: docx, hwpx, pdf
364
+ - Cross-format exports show a warning about potential formatting differences
365
+ - Same-format exports preserve 100% formatting fidelity