Aditi CLI User Interaction Mockup
This document demonstrates typical user interactions with the Aditi CLI, showing the complete workflow from initial setup through successful migration of AsciiDoc files to DITA-compatible format.
Scenario: Technical Writer Migrating Documentation
Sarah is a technical writer with a repository containing 50+ AsciiDoc files that need to be migrated to DITA format. Sheโs heard about Aditi and wants to use it to prepare her files.
1. Initial Setup
First Run - Discovery
$ aditi --help
Usage: aditi [OPTIONS] COMMAND [ARGS]...
AsciiDoc DITA Integration - Prepare AsciiDoc files for migration to DITA
โญโ Options โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ --version -V Show version and exit โ
โ --verbose -v Enable verbose output โ
โ --help Show this message and exit. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โญโ Commands โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ init Initialize Vale configuration for AsciiDocDITA rules. โ
โ check Check AsciiDoc files for DITA compatibility issues. โ
โ fix Fix deterministic DITA compatibility issues in AsciiDoc files. โ
โ journey Start an interactive journey to migrate AsciiDoc files to DITA. โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
$ aditi --version
aditi version 0.1.0
Initialize Vale Configuration
$ aditi init
[17:21:26] INFO Created Vale configuration at .vale.ini
INFO Downloading AsciiDocDITA styles...
[17:21:27] INFO Successfully downloaded AsciiDocDITA styles
โ ผ Pulling Vale container image...
โ ผ Creating Vale configuration...
โ Aditi initialized successfully!
Vale configuration created at: .vale.ini
AsciiDocDITA styles downloaded to: .vale/styles/
Next steps:
1. Run 'aditi check' to validate your AsciiDoc files
2. Run 'aditi journey' for a guided migration workflow
2. First Check - Discovery Phase
Running Check on Documentation
$ aditi check docs/
๐ Analyzing AsciiDoc files in docs/
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 100% 0:00:12
๐ Analysis Results for docs/
๐ด EntityReference (23 violations)
docs/concepts/overview.adoc:15 Replace ' ' with '{nbsp}'
docs/concepts/overview.adoc:23 Replace '—' with '{mdash}'
docs/concepts/overview.adoc:45 Replace '©' with '{copy}'
docs/procedures/install.adoc:12 Replace '™' with '{trade}'
... and 19 more
๐ก ContentType (8 violations)
docs/procedures/install.adoc:1 Missing content type attribute (detected: PROCEDURE)
docs/concepts/overview.adoc:1 Missing content type attribute (detected: CONCEPT)
docs/reference/api.adoc:1 Missing content type attribute (detected: REFERENCE)
... and 5 more
๐ต TaskSection (3 violations)
docs/procedures/install.adoc:34 Task sections require numbered lists
docs/procedures/config.adoc:22 Task sections require numbered lists
docs/procedures/deploy.adoc:45 Task sections require numbered lists
๐ Summary:
Files processed: 12
Total violations: 34
Fully deterministic fixes: 23 (can be auto-fixed)
Partially deterministic fixes: 8 (require review)
Manual intervention required: 3
โจ Good news! 68% of issues can be fixed automatically.
Next steps:
Run 'aditi fix' to apply automatic fixes
Run 'aditi journey' for guided workflow with git integration
3. Guided Journey - Interactive Workflow
Starting the Journey
$ aditi journey
๐ Welcome to Aditi's guided migration journey!
This interactive workflow will help you:
โ Configure Aditi for your repository
โ Create a feature branch for changes
โ Apply fixes systematically
โ Review and commit changes
โ Create a pull request
๐ Current directory: /home/sarah/product-docs
๐ Git repository detected
? Is this the repository you want to work with? (Y/n) Y
? What's your default branch? (main) main
? Would you like to configure any subdirectory permissions? (y/N) y
? Which directories should Aditi process? (Space to select, Enter to confirm)
โฏโ docs/
โ internal/
โฏ archived/
โ modules/
โ Configuration saved to ~/aditi-data/config.json
? What would you like to name your feature branch?
Suggested: aditi/2025-07-27-asciidoc-dita-migration
> aditi/dita-migration-phase1
Creating feature branch...
๐ Please run the following git commands:
[bold blue]Git Command: Create and switch to new branch[/bold blue]
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ git checkout -b aditi/dita-migration-phase1 โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
? Have you created the branch? (Y/n) Y
โ Great! Let's start migrating your files.
4. Applying Fixes - Rule by Rule
EntityReference Rule (Fully Deterministic)
๐ง Processing EntityReference violations (23 found)
These violations can be fixed automatically:
โข โ {nbsp}
โข — โ {mdash}
โข © โ {copy}
โข ™ โ {trade}
? Apply all EntityReference fixes? (Y/n) Y
โ Applying fixes...
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 100% 0:00:03
โ Successfully applied 23 EntityReference fixes
๐ Files modified:
โข docs/concepts/overview.adoc (3 fixes)
โข docs/procedures/install.adoc (1 fix)
โข docs/reference/api.adoc (5 fixes)
โข ... and 6 more files
? Review the changes? (Y/n) Y
[Shows diff output with color highlighting]
? Commit these changes? (Y/n) Y
๐ Suggested commit message:
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Fix EntityReference issues in AsciiDoc files โ
โ โ
โ Fixed the following AsciiDocDITA rules: โ
โ - EntityReference โ
โ โ
โ Files updated: โ
โ - docs/concepts/overview.adoc โ
โ - docs/procedures/install.adoc โ
โ - docs/reference/api.adoc โ
โ - ... and 6 more files โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
? Use this commit message? (Y/n) Y
๐ Please run the following git commands:
[bold blue]Git Command: Stage changes[/bold blue]
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ git add docs/concepts/overview.adoc โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
[bold blue]Git Command: Stage changes[/bold blue]
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ git add docs/procedures/install.adoc โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
... more git add commands ...
[bold blue]Git Command: Create commit[/bold blue]
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ git commit -m "Fix EntityReference issues in AsciiDoc filesโ
โ โ
โ Fixed the following AsciiDocDITA rules: โ
โ - EntityReference โ
โ โ
โ Files updated: โ
โ - docs/concepts/overview.adoc โ
โ - docs/procedures/install.adoc โ
โ - docs/reference/api.adoc โ
โ - ... and 6 more files" โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
? Have you committed the changes? (Y/n) Y
โ Excellent! EntityReference fixes committed.
ContentType Rule (Partially Deterministic)
๐ง Processing ContentType violations (8 found)
These files are missing content type attributes:
1. docs/procedures/install.adoc
Detected type: PROCEDURE (based on filename prefix)
? Apply detected content type?
โฏ Yes, add ':_mod-docs-content-type: PROCEDURE'
No, I'll set it manually
Skip this file
2. docs/concepts/overview.adoc
Detected type: CONCEPT (based on filename prefix)
? Apply detected content type?
โฏ Yes, add ':_mod-docs-content-type: CONCEPT'
No, let me choose:
โ ASSEMBLY
โ CONCEPT
โ PROCEDURE
โ REFERENCE
โ SNIPPET
Skip this file
[... continues for each file ...]
โ Applying content type fixes...
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 100% 0:00:02
โ Successfully applied 8 ContentType fixes
โข 6 automatic detections accepted
โข 2 manually specified
? Review and commit these changes? (Y/n) Y
[Shows diff, commit flow similar to above]
TaskSection Rule (Non-Deterministic)
๐ง Processing TaskSection violations (3 found)
These violations require manual intervention:
๐ docs/procedures/install.adoc:34
โ ๏ธ Task sections must use numbered lists
Current:
โข Download the installer
โข Run the setup wizard
โข Configure settings
Should be:
1. Download the installer
2. Run the setup wizard
3. Configure settings
? How would you like to proceed?
โฏ Open file in editor
Mark with TODO comment
Skip for now
View more context
[If "Mark with TODO comment" selected:]
โ Added TODO comment to docs/procedures/install.adoc:34
// TODO: [Aditi] Convert to numbered list for DITA compatibility
? Continue with next violation? (Y/n) Y
[... continues for remaining violations ...]
5. Completion and Pull Request
Summary and Next Steps
๐ Migration journey complete!
๐ Final Summary:
โ EntityReference: 23 fixes applied (committed)
โ ContentType: 8 fixes applied (committed)
โ ๏ธ TaskSection: 3 marked with TODO comments (committed)
๐ Modified files: 12
๐พ Commits created: 3
๐ฟ Current branch: aditi/dita-migration-phase1
? Ready to create a pull request? (Y/n) Y
๐ Suggested PR details:
Title: "Prepare AsciiDoc files for DITA migration"
Description:
This PR prepares our AsciiDoc documentation for DITA migration by fixing
compatibility issues identified by the AsciiDocDITA ruleset.
## Changes Made
### Automated Fixes
- **EntityReference** (23 fixes): Replaced HTML entities with AsciiDoc equivalents
- **ContentType** (8 fixes): Added missing content type attributes
### Manual Review Required
- **TaskSection** (3 issues): Marked with TODO comments for manual conversion
## Testing
- All files validated with Vale AsciiDocDITA rules
- No AsciiDoc syntax errors introduced
- Preview builds successfully
## Next Steps
1. Review and address TODO comments
2. Run full DITA conversion test
3. Update CI pipeline if needed
? Create PR with GitHub CLI? (Y/n) Y
๐ Please run the following command:
[bold blue]GitHub CLI: Create pull request[/bold blue]
โญโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ gh pr create --base main --title "Prepare AsciiDoc files for DITA โ
โ migration" --body "$(cat <<'EOF' โ
โ This PR prepares our AsciiDoc documentation for DITA migration by fixing โ
โ compatibility issues identified by the AsciiDocDITA ruleset. โ
โ โ
โ ## Changes Made โ
โ โ
โ ### Automated Fixes โ
โ - **EntityReference** (23 fixes): Replaced HTML entities โ
โ - **ContentType** (8 fixes): Added content type attributes โ
โ โ
โ ### Manual Review Required โ
โ - **TaskSection** (3 issues): Marked with TODO comments โ
โ โ
โ ## Testing โ
โ - All files validated with Vale AsciiDocDITA rules โ
โ - No AsciiDoc syntax errors introduced โ
โ - Preview builds successfully โ
โ EOF โ
โ )" โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
? PR created? (Y/n) Y
โจ Congratulations! Your AsciiDoc files are now ready for DITA migration.
๐ Resources:
โข View detailed report: ~/aditi-data/reports/2025-07-27-migration-report.md
โข Review TODO items: git grep "TODO: \[Aditi\]"
โข Run verification: aditi check --strict
Thank you for using Aditi! ๐
6. Subsequent Runs - Incremental Progress
Checking Progress After Manual Fixes
$ aditi check docs/
๐ Analyzing AsciiDoc files in docs/
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 100% 0:00:10
๐ Analysis Results for docs/
โ
EntityReference - No violations found!
โ
ContentType - No violations found!
๐ต TaskSection (3 violations)
docs/procedures/install.adoc:34 Task sections require numbered lists
docs/procedures/config.adoc:22 Task sections require numbered lists
docs/procedures/deploy.adoc:45 Task sections require numbered lists
๐ Summary:
Files processed: 12
Total violations: 3 (down from 34!)
Manual intervention required: 3
๐ฏ Progress: 91% of issues resolved!
Great work! Only manual fixes remain.
Key Features Demonstrated
- Progressive Disclosure: Commands provide increasing detail as needed
- Non-Invasive Git Integration: Suggests commands but doesnโt execute them
- Smart Detection: Analyzes files to suggest appropriate fixes
- Interactive Choices: User maintains control over all changes
- Clear Progress Tracking: Visual indicators and summaries throughout
- Helpful Context: Shows before/after examples and explanations
- Graceful Degradation: Handles errors and allows skipping problematic files
- Comprehensive Reporting: Detailed logs and reports for documentation
This mockup demonstrates how Aditi guides users through the migration process while keeping them in control, providing clear feedback, and ensuring a smooth workflow from start to finish.