moai-adk 0.8.0__tar.gz → 0.8.2__tar.gz

{moai_adk-0.8.0 → moai_adk-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.8.0
+Version: 0.8.2
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -646,6 +646,231 @@ claude
 
 ---
 
+## Development Setup for Contributors
+
+If you're developing **MoAI-ADK itself**, follow these steps to set up your development environment.
+
+### Prerequisites
+
+- Python 3.13+
+- `uv` package manager
+- Git
+
+### Setup Steps
+
+#### Step 1: Clone and Install in Editable Mode
+
+```bash
+# Clone the repository
+git clone https://github.com/modu-ai/moai-adk.git
+cd moai-adk
+
+# Install in editable mode (creates symlink, not a copy)
+uv pip install -e .
+
+# Or with pip (also works)
+pip install -e .
+```
+
+The editable install allows your local changes to be immediately reflected when using `moai-adk` command.
+
+#### Step 2: Initialize Development Configuration
+
+After the editable install, initialize the development repository's configuration:
+
+```bash
+# Run the initialization script
+bash .moai/scripts/init-dev-config.sh
+```
+
+**What this script does:**
+- Extracts the actual version from `pyproject.toml`
+- Replaces template placeholders (`{{MOAI_VERSION}}`) with actual version values in `.moai/config.json`
+- Sets up `project.template_version` field
+- Ensures the `moai-adk update` command works correctly on first run
+
+**Why is this necessary?**
+
+When you install MoAI-ADK in editable mode, the `.moai/config.json` file contains unsubstituted template placeholders. This causes the first `moai-adk update` command to fail with version comparison errors. The init script resolves these placeholders so everything works seamlessly.
+
+#### Step 3: Verify Setup
+
+```bash
+# Check that moai-adk works
+moai-adk --version
+
+# Run the health check
+moai-adk doctor
+
+# Expected output:
+# ✅ Python version: 3.13+
+# ✅ UV installed
+# ✅ Project structure: Valid
+# ✅ Configuration: Ready
+```
+
+#### Step 4: Run Tests
+
+```bash
+# Run all tests with coverage
+pytest tests/
+
+# Run specific test module
+pytest tests/unit/test_update.py -v
+
+# Run with coverage report
+pytest tests/ --cov=src/moai_adk --cov-report=html
+
+# Check coverage thresholds
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+```
+
+### Common Development Workflow
+
+#### After Making Code Changes
+
+```bash
+# 1. Run tests to ensure nothing broke
+pytest tests/ -v
+
+# 2. Check code style
+ruff check src/
+ruff format src/
+
+# 3. Type checking
+mypy src/
+
+# 4. If you modified update.py, test the update command
+moai-adk update --check
+```
+
+#### Testing the Update Command
+
+The update command has been fixed to handle invalid version strings gracefully. To test it in development:
+
+```bash
+# Test update without applying it
+moai-adk update --check
+
+# Test with force mode (skips backup)
+moai-adk update --force
+
+# Test with specific version
+moai-adk update --templates-only
+```
+
+### Understanding the Init Script
+
+The `.moai/scripts/init-dev-config.sh` script performs these operations:
+
+1. **Extracts Version**: Reads `pyproject.toml` to get the current version
+2. **Updates Config**: Modifies `.moai/config.json` to set:
+   - `moai.version` → actual version value
+   - `project.template_version` → actual version value
+3. **Validates**: Ensures the JSON structure is preserved correctly
+4. **Provides Feedback**: Shows what was updated and verifies the changes
+
+### Troubleshooting Development Setup
+
+#### Problem: `moai-adk` command not found
+
+```bash
+# Solution 1: Reinstall in editable mode
+uv pip install -e .
+
+# Solution 2: Verify uv environment
+uv pip list | grep moai-adk
+
+# Solution 3: Use full path
+python -m moai_adk --version
+```
+
+#### Problem: `.moai/config.json` still has placeholders after running init script
+
+```bash
+# Manually check the config
+cat .moai/config.json | grep -i moai_version
+
+# If still showing {{MOAI_VERSION}}, rerun the script:
+bash .moai/scripts/init-dev-config.sh
+
+# Or manually update using Python:
+python3 << 'EOF'
+import json
+from pathlib import Path
+
+config_path = Path(".moai/config.json")
+config = json.loads(config_path.read_text())
+
+# Update manually
+config['moai']['version'] = "0.8.1"
+config['project']['template_version'] = "0.8.1"
+
+config_path.write_text(json.dumps(config, indent=2) + '\n')
+print("✅ Config updated manually")
+EOF
+```
+
+#### Problem: `moai-adk update` requires running twice
+
+This issue has been **fixed** in v0.8.1+. If you're experiencing this:
+
+1. Ensure you've run the init script: `bash .moai/scripts/init-dev-config.sh`
+2. Update to the latest version: `pip install -e --upgrade .`
+3. Verify the config has actual versions: `cat .moai/config.json | grep version`
+
+**What was the issue?**
+- Development installations had unsubstituted `{{MOAI_VERSION}}` placeholders in config
+- First `moai-adk update` would fail comparing "0.8.1" vs "{{MOAI_VERSION}}"
+- Second run might partially work after partial sync
+
+**How it's fixed:**
+- `init-dev-config.sh` replaces placeholders with actual versions
+- Code now gracefully handles InvalidVersion exceptions
+- Added comprehensive unit tests for placeholder detection
+
+### Contributing Tests
+
+When adding new features, always include tests:
+
+```bash
+# Add tests to tests/unit/ or tests/integration/
+# Follow existing test patterns in test_update.py
+
+# Run your new tests
+pytest tests/unit/test_*.py -v
+
+# Ensure coverage remains ≥ 85%
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+```
+
+### Making a Pull Request
+
+Before opening a PR, ensure:
+
+```bash
+# 1. All tests pass
+pytest tests/ -v
+
+# 2. Coverage is adequate
+pytest tests/ --cov=src/moai_adk --cov-report=term-missing
+
+# 3. Code is formatted
+ruff format src/
+ruff check src/
+
+# 4. Types are valid
+mypy src/
+
+# 5. Init script works
+bash .moai/scripts/init-dev-config.sh
+
+# 6. Update command works
+moai-adk update --check
+```
+
+---
+
 ## Core Workflow (0 → 3)
 
 Alfred iteratively develops projects with four commands.
@@ -696,8 +921,11 @@ graph TD
 | `/alfred:1-plan <description>` | Analyze requirements, draft SPEC, write Plan Board                | `.moai/specs/SPEC-*/spec.md`, plan/acceptance docs, feature branch |
 | `/alfred:2-run <SPEC-ID>`      | Execute TDD, test/implement/refactor, verify quality              | `tests/`, `src/` implementation, quality report, TAG connection    |
 | `/alfred:3-sync`               | Sync docs/README/CHANGELOG, organize TAG/PR status                | `docs/`, `.moai/reports/sync-report.md`, Ready PR                  |
+| `/alfred:9-feedback` | Interactively create GitHub Issues (type → title → description → priority) | GitHub Issue with auto labels, priority, URL        |
 
 > ❗ All commands maintain **Phase 0 (optional) → Phase 1 → Phase 2 → Phase 3** cycle structure. Alfred automatically reports execution status and next-step suggestions.
+>
+> 💡 **New in v0.7.0+**: `/alfred:9-feedback` enables instant GitHub Issue creation during development, keeping your workflow uninterrupted while keeping issues tracked and visible to the team.
 
 ---
 
@@ -814,6 +1042,125 @@ When working in your **local development environment**, CodeRabbit provides auto
 
 ---
 
+## Quick Issue Creation with `/alfred:9-feedback`
+
+MoAI-ADK v0.7.0+ includes the **Quick Issue Creation** feature, allowing developers to instantly create GitHub Issues without interrupting their development workflow.
+
+### Why Quick Issue Creation?
+
+During development, you frequently encounter:
+- 🐛 Bugs that need immediate reporting
+- ✨ Feature ideas that come to mind
+- ⚡ Performance improvements to suggest
+- ❓ Architecture questions that need team discussion
+
+**The old way**: Stop coding, go to GitHub, manually fill issue form, remember what you were working on.
+**The new way**: Type one command, GitHub Issue is created instantly, continue coding.
+
+### Interactive Dialog Flow
+
+When you run `/alfred:9-help`, Alfred guides you through an interactive multi-step dialog:
+
+**Step 1: Select Issue Type**
+```
+Alfred: What type of issue do you want to create?
+[ ] 🐛 Bug Report - Something isn't working
+[ ] ✨ Feature Request - Suggest new functionality
+[ ] ⚡ Improvement - Enhance existing features
+[ ] ❓ Question/Discussion - Ask the team
+```
+
+**Step 2: Enter Issue Title**
+```
+Alfred: What's the issue title?
+Your input: "Login button not responding to clicks"
+```
+
+**Step 3: Enter Description (Optional)**
+```
+Alfred: Provide a detailed description (optional—press Enter to skip)
+Your input: "When I click the login button on iPhone 15, it freezes for 5 seconds then crashes"
+```
+
+**Step 4: Select Priority Level**
+```
+Alfred: What's the priority level?
+[ ] 🔴 Critical - System down, data loss, security breach
+[ ] 🟠 High - Major feature broken, significant impact
+[✓] 🟡 Medium - Normal priority (default)
+[ ] 🟢 Low - Minor issues, nice-to-have
+```
+
+**Step 5: Automatic Issue Creation**
+```
+Alfred automatically:
+1. Determines appropriate labels based on issue type and priority
+2. Formats title with emoji: "🐛 [BUG] Login button not responding..."
+3. Creates GitHub Issue with all information
+4. Returns the issue number and URL
+```
+
+### Key Features
+
+1. **⚡ Instant Creation**: Create GitHub Issues in seconds
+2. **🏷️ Automatic Labels**: Issue type + priority automatically labeled
+3. **🎯 Priority Selection**: Choose from Critical/High/Medium/Low
+4. **🔗 Team Visibility**: Issues immediately visible and discussable
+5. **📋 Standardized Format**: All issues follow consistent structure
+
+### Complete Example: Bug Report During Code Review
+
+```bash
+# During code review, you notice a critical issue and want to report it instantly
+$ /alfred:9-feedback
+
+Alfred: What type of issue do you want to create?
+> 🐛 Bug Report
+
+Alfred: What's the issue title?
+> Login button crash on mobile devices
+
+Alfred: Provide a detailed description (optional—press Enter to skip)
+> Tapping the login button on iPhone 15 causes app to freeze for 5 seconds then crash.
+> Tested on iOS 17.2, Chrome 120 on macOS 14.2.
+> Expected: Login modal should appear
+> Actual: No response then crash
+
+Alfred: What's the priority level?
+> 🟠 High
+
+✅ GitHub Issue #234 created successfully!
+
+📋 Title: 🐛 [BUG] Login button crash on mobile devices
+🟠 Priority: High
+🏷️  Labels: bug, reported, priority-high
+🔗 URL: https://github.com/owner/repo/issues/234
+
+💡 Next: Continue with your work—the issue is now tracked!
+```
+
+### Integration with MoAI-ADK Workflow
+
+1. **During Development**: Use `/alfred:9-help` to report bugs/ideas instantly
+2. **In Code Review**: Convert improvement suggestions to tracked issues
+3. **When Planning**: Reference created issues in SPEC documents
+4. **During Sync**: Link issues to SPEC requirements with `/alfred:3-sync`
+
+### Prerequisites
+
+- GitHub CLI (`gh`) installed and authenticated
+- Repository initialized with Git
+
+### Learn More
+
+See `.moai/docs/quick-issue-creation-guide.md` for comprehensive documentation including:
+- Detailed usage examples
+- Best practices and tips
+- Troubleshooting guide
+- Integration with SPEC documents
+
+---
+
 ## 5 Key Concepts
 
 MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and together they create a powerful development system.