A toolkit for authoring and reviewing AsciiDoc books.
This gem brings together practical lessons from the author's experience writing and publishing books, along with a selection of the tools originally developed for that work. Those projects include CyberGarage technical books in English and Japanese, and books on health, exercise, and sports science published under WellBeing Lab. The experience informs the toolkit's writing criteria, contextual review prompts, and checks for preserving manuscript content during revision.
The following commands are available in version 1.4.1.
| Feature | Commands | Behavior |
|---|---|---|
| Document images | image list, image stats, image find, image scale |
Inspect and filter referenced block images; preview or explicitly apply source display widths |
| Document outline | document toc |
Print parsed section titles as text or JSON, including source locations, with optional depth and outline numbering |
| Book metadata | document info |
Extract book attributes as text or JSON |
| Cross-reference checks | document check-xrefs |
Report unresolved local cross-references with source locations |
| Document-title index | document index |
Generate an alphabetical AsciiDoc index from English document titles and IDs |
| Replacement preview | replace check, replace diff |
Report mechanical replacement candidates or preview a diff for mapped running prose; preserve source files |
| Replacement application | replace apply |
Apply author-supplied rules after checking protected content and document structure; no MeCab or AI required |
| Prose review | review scan |
Collect mapped Japanese running prose and contextual review candidates with MeCab/IPADIC by default |
| List review | review scan --scope lists |
Review mapped single-line list text in a separate session |
| Heading review | review scan --scope headings |
Collect editable section titles separately, retaining the outline and read-only body evidence |
| Review prompts | review prompt |
Generate one Markdown prompt from a saved session for review and editing by an external reviewer |
| Baseline verification | review verify |
Check edited sources against a saved baseline for mechanical preservation; meaning is not verified |
| Manuscript scoring | review score |
Report a prose candidate-density score; explicit --agent codex or --agent claude optionally invokes a local AI CLI for readability ratings |
| Writing criteria and prompts | writing criteria, writing prompt |
Print Japanese prose criteria or generate a writing prompt without a manuscript or MeCab |
| Skill registration | skill list, skill install, skill status, skill upgrade |
Register bundled skills for Codex or Claude and inspect or upgrade managed copies while protecting local changes |
Ruby 3.2 or later is required; RubyGems installs Asciidoctor and the other Ruby
dependencies. Document inspection and replacement require neither MeCab nor an
AI CLI. Japanese review and scoring use external MeCab with UTF-8 IPADIC by
default. See installation and analyzer setup.
Explicit --tokenizer literal offers limited phrase matching without MeCab.
Document commands accept any language. Version 1.3.0 adds
--lang en to writing and review, including scoring, headings and lists.
Replacement remains Japanese-only. See English review
for boundaries, rules and score limits. Node.js and textlint are not required.
Only replace apply edits manuscripts directly. Review prompts guide an external
human or agent; scan, prompt, verify, and scoring do not edit manuscripts.
Only explicit review score --agent codex or --agent claude invokes an
installed AI CLI, which may use its configured model provider.
Findings are review candidates; verification checks mechanical preservation and
keeps meaning_verified: false. The CLI does not publish books or provide EPUB,
image, or book scaffolding commands.
The packaged prose rules also flag broad operation and degree wording such as
分かる, 置く, 変える, 発火, 短い, 長い, and 作れます for contextual
review. Precise everyday language may remain; see the review guide.
gem install asciidoc-pubkit
asciidoc-pubkit --version
asciidoc-pubkit --helpTo update, run gem update asciidoc-pubkit. For Bundler, add
gem 'asciidoc-pubkit', '~> 1.2.0' to your project's Gemfile and run commands
through bundle exec. See source installation and local checkout usage.
The checkout also adds 作用 as an advisory noun candidate. Compare its
actual operation, classification, result, or state change in context; see
operation-effect cues.
Follow the agent review tutorial for a complete scan, prompt, Codex/Claude handoff, revision and verification walkthrough. For a reusable agent workflow, see skill integration.
Run these commands from the manuscript directory:
asciidoc-pubkit document toc book.adoc --depth 2 --numbered
asciidoc-pubkit document info book.adoc --json
asciidoc-pubkit document check-xrefs book.adoc
asciidoc-pubkit replace check book.adoc --rules replacements.yml
asciidoc-pubkit replace diff book.adoc --rules replacements.yml
asciidoc-pubkit replace apply book.adoc --rules replacements.yml
# Establish a review baseline after mechanical replacements.
asciidoc-pubkit review scan book.adoc --output .pubkit/review
asciidoc-pubkit review prompt .pubkit/review --output review-prompt.md
# Ask your reviewer to read the prompt and edit the referenced manuscript.
asciidoc-pubkit review verify .pubkit/review --output verification.jsonReplacement requires author-supplied replacement rules;
review candidates are never applied as replacements. replace check exits 1
when candidates exist. Output files must be new.
Prose, headings, and lists use separate review sessions. For a complete review, finish and verify headings first, then prose, then lists, creating each baseline after the preceding phase. See the review workflow and list review for supported spans and coverage limits.
To score prose or generate writing guidance:
asciidoc-pubkit review score book.adoc
asciidoc-pubkit writing criteria --lang ja
asciidoc-pubkit writing prompt --lang ja --output writing-prompt.mdExisting review sessions require the exact tool version that created them. Before upgrading, finish ongoing reviews with that version or preserve their baselines and start a new review in a separate directory with v1.3.1. A new scan cannot verify preservation relative to an earlier baseline.
| Guide | Contents |
|---|---|
| Installation | RubyGems, Bundler, source, local checkout, MeCab/IPADIC |
| Document commands | Outline, metadata, cross-references, English-title indexes |
| Outline review | JSON outline, heading-depth selection, whole-outline prompts and preservation |
| Prose replacements | Rule format, imports, regex compatibility, preview/apply, preservation |
| Skill commands | List/install/status/upgrade, managed files, local changes and recovery |
| Skill integration | Register and maintain a skill, then orchestrate review in any book project |
| Agent review tutorial | Illustrated first review, agent instructions, sequential scopes and verification recovery |
| Review workflow | Scanning, heading review, prompts, sessions, verification, exit codes |
| List review | Separate list sessions, editable items, protected syntax |
| Scoring | Candidate density, optional AI readability ratings, output |
| Writing | Shared Japanese criteria and writing prompts |
| Configuration | Discovery, precedence, paths, glossary, exclusions |
| Rules and coverage | Candidate detection, source positions, scope, session compatibility |
| Custom review rules | Complete rule replacement, strict YAML schema, saved rules |
| Architecture | Review principles, analysis pipeline, scoring algorithms |
| Development | Setup, test suite, development validation |
| Prose evaluation | Fixed fixtures, detector metrics, AI trials, before/after comparisons |
| References | Editorial and research foundations |
| English review | English lexical matching, rules and preservation limits |
| English evaluation | Detection corpus, score baseline and editorial calibration |
| English review research | Historical research and design decisions |
See CHANGELOG.md for release history.
Japanese writing and new review prompts compare 段階 with フェーズ for
processing divisions, while preserving timing and progressive disclosure. See
phase terminology guidance.
This does not add detector rules or automatic replacement.
New scans flag とはみなしません and とみなしません for contextual comparison
with direct evidence-limit predicates. Preserve interpretation policies, missing
evidence and conditions; see interpretation limits.
These hints do not automatically replace text or establish writing quality.
Copyright 2026 CyberGarage.
Licensed under the Apache License, Version 2.0. See LICENSE.