aios-core 2.1.5 → 2.2.0

package/.aios-core/core/docs/SHARD-TRANSLATION-GUIDE.md

@@ -1,335 +1,335 @@
-# Document Sharding with Portuguese-to-English Translation
-
-## Overview
-
-AIOS-FULLSTACK now automatically translates Portuguese documentation into English filenames when sharding documents. This ensures consistency across all projects and compatibility with hardcoded English filenames in configuration files.
-
-## Problem Solved
-
-**Before:** Sharding a Portuguese PRD/Architecture resulted in filenames like:
-- `viso-do-produto.md` (missing accent, Portuguese)
-- `pilha-tecnolgica.md` (missing accent, Portuguese)
-- `padroes-de-codigo.md` (missing accent, Portuguese)
-
-**After:** Sharding now produces proper English filenames:
-- `product-vision.md` ✅
-- `tech-stack.md` ✅
-- `coding-standards.md` ✅
-
-## How It Works
-
-### 1. Automatic Translation During Shard
-
-When you run `*shard` (PO or Architect), the system:
-
-1. **Detects language** by checking for Portuguese characters/terms
-2. **Translates** section headings using built-in dictionary
-3. **Normalizes** to `lowercase-dash-case`
-4. **Removes** accents and special characters
-5. **Creates** files with English names
-
-### 2. Translation Dictionary
-
-The shard task includes 60+ Portuguese→English mappings:
-
-```yaml
-Common Terms:
-- visão → vision
-- produto → product
-- arquitetura → architecture
-- pilha tecnológica → tech-stack
-- padrões de código → coding-standards
-- requisitos → requirements
-- testes → tests
-# ... and many more
-```
-
-**See full dictionary:** `.aios-core/tasks/shard-doc.md` (Section 3)
-
-### 3. Fallback System
-
-If the Agent needs architecture files and finds Portuguese names:
-
-**Order of attempts:**
-1. `tech-stack.md` (primary)
-2. `technology-stack.md` (fallback)
-3. `pilha-tecnologica.md` (Portuguese fallback)
-
-**Configuration:** `.aios-core/core-config.yaml`
-
-```yaml
-devLoadAlwaysFiles:
-  - docs/architecture/coding-standards.md
-  - docs/architecture/tech-stack.md
-  - docs/architecture/source-tree.md
-
-devLoadAlwaysFilesFallback:
-  - docs/architecture/padroes-de-codigo.md
-  - docs/architecture/pilha-tecnologica.md
-  - docs/architecture/code-standards.md
-  # ... more alternatives
-```
-
-## Usage
-
-### Creating New Documentation
-
-#### Option 1: Write in English (Recommended)
-```bash
-# Write your PRD in English
-docs/prd.md
-
-# Shard normally
-*shard docs/prd.md docs/prd
-
-# Result: All English filenames automatically
-```
-
-#### Option 2: Write in Portuguese
-```bash
-# Write your PRD in Portuguese
-docs/prd.md
-
-# Shard with automatic translation
-*shard docs/prd.md docs/prd
-
-# Result: Portuguese content, English filenames
-# Example: "## Visão do Produto" → product-vision.md
-```
-
-### Validating Filenames
-
-After sharding, validate that all filenames are correct:
-
-```bash
-# Check for issues
-node .aios-core/scripts/validate-filenames.js
-
-# Auto-fix issues (renames files)
-node .aios-core/scripts/validate-filenames.js --fix
-```
-
-**What the validator checks:**
-- ❌ Portuguese characters (á, ã, ç, etc.)
-- ❌ Portuguese terms (visão, pilha, padrões)
-- ✅ English standard names
-
-### Fixing Existing Projects
-
-If you have an existing project with Portuguese filenames:
-
-```bash
-# 1. Backup current docs
-cp -r docs docs.backup-portuguese
-
-# 2. Validate to see issues
-node .aios-core/scripts/validate-filenames.js
-
-# 3. Auto-fix (renames files)
-node .aios-core/scripts/validate-filenames.js --fix
-
-# 4. Or re-shard from original
-*shard docs/prd.md docs/prd
-*shard docs/architecture.md docs/architecture
-```
-
-## Translation Examples
-
-| Portuguese Heading | English Filename |
-|-------------------|------------------|
-| ## Visão do Produto | `product-vision.md` |
-| ## Pilha Tecnológica | `tech-stack.md` |
-| ## Padrões de Código | `coding-standards.md` |
-| ## Estrutura do Projeto | `project-structure.md` |
-| ## Requisitos Funcionais | `functional-requirements.md` |
-| ## Estratégia de Testes | `testing-strategy.md` |
-| ## Banco de Dados - Esquema | `database-schema.md` |
-| ## API Design (tRPC) | `api-design-trpc.md` |
-| ## Riscos Técnicos | `technical-risks.md` |
-| ## Infraestrutura | `infrastructure.md` |
-
-## Advanced: Adding Custom Translations
-
-### For Project-Specific Terms
-
-Edit `.aios-core/tasks/shard-doc.md`, Section 3:
-
-```yaml
-# Add your custom translations
-Custom Terms:
-  seu-termo: your-term
-  termo-específico: specific-term
-```
-
-### For New Languages
-
-The system can be extended to support other languages by:
-
-1. Adding language detection logic
-2. Creating translation dictionary for that language
-3. Updating the filename generation algorithm
-
-## Troubleshooting
-
-### Problem: Files still have Portuguese names
-
-**Solution:**
-1. Check you're using the updated `.aios-core/tasks/shard-doc.md`
-2. Run validator to confirm: `node .aios-core/scripts/validate-filenames.js`
-3. Use `--fix` flag to auto-correct
-
-### Problem: core-config references missing files
-
-**Solution:**
-The fallback system handles this automatically. Agent will try:
-1. Primary name (English)
-2. Fallback alternatives
-3. Portuguese equivalents
-
-**Manual fix:**
-Edit `.aios-core/core-config.yaml` to add more fallbacks.
-
-### Problem: Some terms aren't translating
-
-**Solution:**
-Add them to the dictionary in `shard-doc.md`:
-
-```yaml
-# Your custom term
-novo-termo: new-term
-```
-
-### Problem: Validation shows false positives
-
-**Solution:**
-If a term is intentionally Portuguese (e.g., company name), add exception to validator:
-
-```javascript
-// .aios-core/scripts/validate-filenames.js
-const ALLOWED_EXCEPTIONS = ['your-term'];
-```
-
-## Best Practices
-
-### ✅ Do
-
-- **Write PRDs/Architecture in your preferred language**
-- **Trust the automatic translation** during shard
-- **Run validator** after sharding to confirm
-- **Use English filenames** in git commits/PRs
-
-### ❌ Don't
-
-- **Manually create files** with Portuguese names
-- **Bypass the shard process** and create docs directly
-- **Mix languages** in single documents (content can be PT, but structure references should be EN)
-- **Hardcode Portuguese filenames** in custom tasks/workflows
-
-## Configuration Reference
-
-### Files Modified by This Feature
-
-```
-.aios-core/
-├── tasks/
-│   ├── shard-doc.md          # Translation logic + dictionary
-│   └── create-next-story.md  # Fallback file loading
-├── core-config.yaml          # Fallback patterns
-└── utils/
-    └── validate-filenames.js # Validation tool
-```
-
-### Key Configuration Options
-
-**Enable/Disable Markdown Exploder:**
-```yaml
-# .aios-core/core-config.yaml
-markdownExploder: true  # Uses md-tree CLI (faster)
-markdownExploder: false # Uses manual method (has translation)
-```
-
-**Note:** Translation currently works best with manual method. The `md-tree` CLI doesn't support translation yet.
-
-## Migration Guide
-
-### From Portuguese to English Filenames
-
-#### Step 1: Assessment
-```bash
-# Check current state
-ls docs/prd/
-ls docs/architecture/
-
-# Count Portuguese files
-node .aios-core/scripts/validate-filenames.js
-```
-
-#### Step 2: Backup
-```bash
-# Backup current structure
-cp -r docs docs.backup-$(date +%Y%m%d)
-```
-
-#### Step 3: Re-shard or Fix
-```bash
-# Option A: Re-shard from source
-*shard docs/prd.md docs/prd
-*shard docs/architecture.md docs/architecture
-
-# Option B: Auto-fix existing files
-node .aios-core/scripts/validate-filenames.js --fix
-```
-
-#### Step 4: Verify
-```bash
-# Confirm all files are English
-node .aios-core/scripts/validate-filenames.js
-
-# Check stories can find files
-*create-story  # Test story creation
-```
-
-#### Step 5: Update References
-```bash
-# Search for any hardcoded Portuguese filenames
-grep -r "pilha-tecnologica" .
-grep -r "padroes-de-codigo" .
-
-# Update them to English equivalents
-```
-
-## FAQ
-
-**Q: Can I keep writing PRDs in Portuguese?**
-A: Yes! Content can be Portuguese, only filenames will be English.
-
-**Q: What if I want Spanish/French support?**
-A: Open an issue or extend the translation dictionary in `shard-doc.md`.
-
-**Q: Does this work with md-tree CLI?**
-A: Currently, translation works with manual shard method only. We're working on md-tree integration.
-
-**Q: Will this break existing projects?**
-A: No, the fallback system ensures compatibility with both naming conventions.
-
-**Q: How do I add more translations?**
-A: Edit `.aios-core/tasks/shard-doc.md`, Section 3, and add to the YAML dictionary.
-
-## Support
-
-If you encounter issues:
-
-1. Check this guide first
-2. Run the validator: `node .aios-core/scripts/validate-filenames.js`
-3. Review `.aios-core/tasks/shard-doc.md` for translation rules
-4. Open an issue with:
-   - Your PRD heading
-   - Expected filename
-   - Actual filename
-   - Output of validator
-
----
-
-**Last Updated:** January 2025
-**Feature Version:** AIOS v4.x
-**Related Stories:** Translation Enhancement Story 5.2
+# Document Sharding with Portuguese-to-English Translation
+
+## Overview
+
+Synkra AIOS now automatically translates Portuguese documentation into English filenames when sharding documents. This ensures consistency across all projects and compatibility with hardcoded English filenames in configuration files.
+
+## Problem Solved
+
+**Before:** Sharding a Portuguese PRD/Architecture resulted in filenames like:
+- `viso-do-produto.md` (missing accent, Portuguese)
+- `pilha-tecnolgica.md` (missing accent, Portuguese)
+- `padroes-de-codigo.md` (missing accent, Portuguese)
+
+**After:** Sharding now produces proper English filenames:
+- `product-vision.md` ✅
+- `tech-stack.md` ✅
+- `coding-standards.md` ✅
+
+## How It Works
+
+### 1. Automatic Translation During Shard
+
+When you run `*shard` (PO or Architect), the system:
+
+1. **Detects language** by checking for Portuguese characters/terms
+2. **Translates** section headings using built-in dictionary
+3. **Normalizes** to `lowercase-dash-case`
+4. **Removes** accents and special characters
+5. **Creates** files with English names
+
+### 2. Translation Dictionary
+
+The shard task includes 60+ Portuguese→English mappings:
+
+```yaml
+Common Terms:
+- visão → vision
+- produto → product
+- arquitetura → architecture
+- pilha tecnológica → tech-stack
+- padrões de código → coding-standards
+- requisitos → requirements
+- testes → tests
+# ... and many more
+```
+
+**See full dictionary:** `.aios-core/tasks/shard-doc.md` (Section 3)
+
+### 3. Fallback System
+
+If the Agent needs architecture files and finds Portuguese names:
+
+**Order of attempts:**
+1. `tech-stack.md` (primary)
+2. `technology-stack.md` (fallback)
+3. `pilha-tecnologica.md` (Portuguese fallback)
+
+**Configuration:** `.aios-core/core-config.yaml`
+
+```yaml
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/source-tree.md
+
+devLoadAlwaysFilesFallback:
+  - docs/architecture/padroes-de-codigo.md
+  - docs/architecture/pilha-tecnologica.md
+  - docs/architecture/code-standards.md
+  # ... more alternatives
+```
+
+## Usage
+
+### Creating New Documentation
+
+#### Option 1: Write in English (Recommended)
+```bash
+# Write your PRD in English
+docs/prd.md
+
+# Shard normally
+*shard docs/prd.md docs/prd
+
+# Result: All English filenames automatically
+```
+
+#### Option 2: Write in Portuguese
+```bash
+# Write your PRD in Portuguese
+docs/prd.md
+
+# Shard with automatic translation
+*shard docs/prd.md docs/prd
+
+# Result: Portuguese content, English filenames
+# Example: "## Visão do Produto" → product-vision.md
+```
+
+### Validating Filenames
+
+After sharding, validate that all filenames are correct:
+
+```bash
+# Check for issues
+node .aios-core/scripts/validate-filenames.js
+
+# Auto-fix issues (renames files)
+node .aios-core/scripts/validate-filenames.js --fix
+```
+
+**What the validator checks:**
+- ❌ Portuguese characters (á, ã, ç, etc.)
+- ❌ Portuguese terms (visão, pilha, padrões)
+- ✅ English standard names
+
+### Fixing Existing Projects
+
+If you have an existing project with Portuguese filenames:
+
+```bash
+# 1. Backup current docs
+cp -r docs docs.backup-portuguese
+
+# 2. Validate to see issues
+node .aios-core/scripts/validate-filenames.js
+
+# 3. Auto-fix (renames files)
+node .aios-core/scripts/validate-filenames.js --fix
+
+# 4. Or re-shard from original
+*shard docs/prd.md docs/prd
+*shard docs/architecture.md docs/architecture
+```
+
+## Translation Examples
+
+| Portuguese Heading | English Filename |
+|-------------------|------------------|
+| ## Visão do Produto | `product-vision.md` |
+| ## Pilha Tecnológica | `tech-stack.md` |
+| ## Padrões de Código | `coding-standards.md` |
+| ## Estrutura do Projeto | `project-structure.md` |
+| ## Requisitos Funcionais | `functional-requirements.md` |
+| ## Estratégia de Testes | `testing-strategy.md` |
+| ## Banco de Dados - Esquema | `database-schema.md` |
+| ## API Design (tRPC) | `api-design-trpc.md` |
+| ## Riscos Técnicos | `technical-risks.md` |
+| ## Infraestrutura | `infrastructure.md` |
+
+## Advanced: Adding Custom Translations
+
+### For Project-Specific Terms
+
+Edit `.aios-core/tasks/shard-doc.md`, Section 3:
+
+```yaml
+# Add your custom translations
+Custom Terms:
+  seu-termo: your-term
+  termo-específico: specific-term
+```
+
+### For New Languages
+
+The system can be extended to support other languages by:
+
+1. Adding language detection logic
+2. Creating translation dictionary for that language
+3. Updating the filename generation algorithm
+
+## Troubleshooting
+
+### Problem: Files still have Portuguese names
+
+**Solution:**
+1. Check you're using the updated `.aios-core/tasks/shard-doc.md`
+2. Run validator to confirm: `node .aios-core/scripts/validate-filenames.js`
+3. Use `--fix` flag to auto-correct
+
+### Problem: core-config references missing files
+
+**Solution:**
+The fallback system handles this automatically. Agent will try:
+1. Primary name (English)
+2. Fallback alternatives
+3. Portuguese equivalents
+
+**Manual fix:**
+Edit `.aios-core/core-config.yaml` to add more fallbacks.
+
+### Problem: Some terms aren't translating
+
+**Solution:**
+Add them to the dictionary in `shard-doc.md`:
+
+```yaml
+# Your custom term
+novo-termo: new-term
+```
+
+### Problem: Validation shows false positives
+
+**Solution:**
+If a term is intentionally Portuguese (e.g., company name), add exception to validator:
+
+```javascript
+// .aios-core/scripts/validate-filenames.js
+const ALLOWED_EXCEPTIONS = ['your-term'];
+```
+
+## Best Practices
+
+### ✅ Do
+
+- **Write PRDs/Architecture in your preferred language**
+- **Trust the automatic translation** during shard
+- **Run validator** after sharding to confirm
+- **Use English filenames** in git commits/PRs
+
+### ❌ Don't
+
+- **Manually create files** with Portuguese names
+- **Bypass the shard process** and create docs directly
+- **Mix languages** in single documents (content can be PT, but structure references should be EN)
+- **Hardcode Portuguese filenames** in custom tasks/workflows
+
+## Configuration Reference
+
+### Files Modified by This Feature
+
+```
+.aios-core/
+├── tasks/
+│   ├── shard-doc.md          # Translation logic + dictionary
+│   └── create-next-story.md  # Fallback file loading
+├── core-config.yaml          # Fallback patterns
+└── utils/
+    └── validate-filenames.js # Validation tool
+```
+
+### Key Configuration Options
+
+**Enable/Disable Markdown Exploder:**
+```yaml
+# .aios-core/core-config.yaml
+markdownExploder: true  # Uses md-tree CLI (faster)
+markdownExploder: false # Uses manual method (has translation)
+```
+
+**Note:** Translation currently works best with manual method. The `md-tree` CLI doesn't support translation yet.
+
+## Migration Guide
+
+### From Portuguese to English Filenames
+
+#### Step 1: Assessment
+```bash
+# Check current state
+ls docs/prd/
+ls docs/architecture/
+
+# Count Portuguese files
+node .aios-core/scripts/validate-filenames.js
+```
+
+#### Step 2: Backup
+```bash
+# Backup current structure
+cp -r docs docs.backup-$(date +%Y%m%d)
+```
+
+#### Step 3: Re-shard or Fix
+```bash
+# Option A: Re-shard from source
+*shard docs/prd.md docs/prd
+*shard docs/architecture.md docs/architecture
+
+# Option B: Auto-fix existing files
+node .aios-core/scripts/validate-filenames.js --fix
+```
+
+#### Step 4: Verify
+```bash
+# Confirm all files are English
+node .aios-core/scripts/validate-filenames.js
+
+# Check stories can find files
+*create-story  # Test story creation
+```
+
+#### Step 5: Update References
+```bash
+# Search for any hardcoded Portuguese filenames
+grep -r "pilha-tecnologica" .
+grep -r "padroes-de-codigo" .
+
+# Update them to English equivalents
+```
+
+## FAQ
+
+**Q: Can I keep writing PRDs in Portuguese?**
+A: Yes! Content can be Portuguese, only filenames will be English.
+
+**Q: What if I want Spanish/French support?**
+A: Open an issue or extend the translation dictionary in `shard-doc.md`.
+
+**Q: Does this work with md-tree CLI?**
+A: Currently, translation works with manual shard method only. We're working on md-tree integration.
+
+**Q: Will this break existing projects?**
+A: No, the fallback system ensures compatibility with both naming conventions.
+
+**Q: How do I add more translations?**
+A: Edit `.aios-core/tasks/shard-doc.md`, Section 3, and add to the YAML dictionary.
+
+## Support
+
+If you encounter issues:
+
+1. Check this guide first
+2. Run the validator: `node .aios-core/scripts/validate-filenames.js`
+3. Review `.aios-core/tasks/shard-doc.md` for translation rules
+4. Open an issue with:
+   - Your PRD heading
+   - Expected filename
+   - Actual filename
+   - Output of validator
+
+---
+
+**Last Updated:** January 2025
+**Feature Version:** AIOS v4.x
+**Related Stories:** Translation Enhancement Story 5.2