bmalph 1.0.0

package/ralph/templates/AGENT.md

@@ -0,0 +1,158 @@
+# Agent Build Instructions
+
+## Project Setup
+```bash
+# Install dependencies (example for Node.js project)
+npm install
+
+# Or for Python project
+pip install -r requirements.txt
+
+# Or for Rust project  
+cargo build
+```
+
+## Running Tests
+```bash
+# Node.js
+npm test
+
+# Python
+pytest
+
+# Rust
+cargo test
+```
+
+## Build Commands
+```bash
+# Production build
+npm run build
+# or
+cargo build --release
+```
+
+## Development Server
+```bash
+# Start development server
+npm run dev
+# or
+cargo run
+```
+
+## Key Learnings
+- Update this section when you learn new build optimizations
+- Document any gotchas or special setup requirements
+- Keep track of the fastest test/build cycle
+
+## Feature Development Quality Standards
+
+**CRITICAL**: All new features MUST meet the following mandatory requirements before being considered complete.
+
+### Testing Requirements
+
+- **Minimum Coverage**: 85% code coverage ratio required for all new code
+- **Test Pass Rate**: 100% - all tests must pass, no exceptions
+- **Test Types Required**:
+  - Unit tests for all business logic and services
+  - Integration tests for API endpoints or main functionality
+  - End-to-end tests for critical user workflows
+- **Coverage Validation**: Run coverage reports before marking features complete:
+  ```bash
+  # Examples by language/framework
+  npm run test:coverage
+  pytest --cov=src tests/ --cov-report=term-missing
+  cargo tarpaulin --out Html
+  ```
+- **Test Quality**: Tests must validate behavior, not just achieve coverage metrics
+- **Test Documentation**: Complex test scenarios must include comments explaining the test strategy
+
+### Git Workflow Requirements
+
+Before moving to the next feature, ALL changes must be:
+
+1. **Committed with Clear Messages**:
+   ```bash
+   git add .
+   git commit -m "feat(module): descriptive message following conventional commits"
+   ```
+   - Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, etc.
+   - Include scope when applicable: `feat(api):`, `fix(ui):`, `test(auth):`
+   - Write descriptive messages that explain WHAT changed and WHY
+
+2. **Pushed to Remote Repository**:
+   ```bash
+   git push origin <branch-name>
+   ```
+   - Never leave completed features uncommitted
+   - Push regularly to maintain backup and enable collaboration
+   - Ensure CI/CD pipelines pass before considering feature complete
+
+3. **Branch Hygiene**:
+   - Work on feature branches, never directly on `main`
+   - Branch naming convention: `feature/<feature-name>`, `fix/<issue-name>`, `docs/<doc-update>`
+   - Create pull requests for all significant changes
+
+4. **Ralph Integration**:
+   - Update .ralph/@fix_plan.md with new tasks before starting work
+   - Mark items complete in .ralph/@fix_plan.md upon completion
+   - Update .ralph/PROMPT.md if development patterns change
+   - Test features work within Ralph's autonomous loop
+
+### Documentation Requirements
+
+**ALL implementation documentation MUST remain synchronized with the codebase**:
+
+1. **Code Documentation**:
+   - Language-appropriate documentation (JSDoc, docstrings, etc.)
+   - Update inline comments when implementation changes
+   - Remove outdated comments immediately
+
+2. **Implementation Documentation**:
+   - Update relevant sections in this AGENT.md file
+   - Keep build and test commands current
+   - Update configuration examples when defaults change
+   - Document breaking changes prominently
+
+3. **README Updates**:
+   - Keep feature lists current
+   - Update setup instructions when dependencies change
+   - Maintain accurate command examples
+   - Update version compatibility information
+
+4. **AGENT.md Maintenance**:
+   - Add new build patterns to relevant sections
+   - Update "Key Learnings" with new insights
+   - Keep command examples accurate and tested
+   - Document new testing patterns or quality gates
+
+### Feature Completion Checklist
+
+Before marking ANY feature as complete, verify:
+
+- [ ] All tests pass with appropriate framework command
+- [ ] Code coverage meets 85% minimum threshold
+- [ ] Coverage report reviewed for meaningful test quality
+- [ ] Code formatted according to project standards
+- [ ] Type checking passes (if applicable)
+- [ ] All changes committed with conventional commit messages
+- [ ] All commits pushed to remote repository
+- [ ] .ralph/@fix_plan.md task marked as complete
+- [ ] Implementation documentation updated
+- [ ] Inline code comments updated or added
+- [ ] .ralph/@AGENT.md updated (if new patterns introduced)
+- [ ] Breaking changes documented
+- [ ] Features tested within Ralph loop (if applicable)
+- [ ] CI/CD pipeline passes
+
+### Rationale
+
+These standards ensure:
+- **Quality**: High test coverage and pass rates prevent regressions
+- **Traceability**: Git commits and .ralph/@fix_plan.md provide clear history of changes
+- **Maintainability**: Current documentation reduces onboarding time and prevents knowledge loss
+- **Collaboration**: Pushed changes enable team visibility and code review
+- **Reliability**: Consistent quality gates maintain production stability
+- **Automation**: Ralph integration ensures continuous development practices
+
+**Enforcement**: AI agents should automatically apply these standards to all feature development tasks without requiring explicit instruction for each task.

package/ralph/templates/PROMPT.md

@@ -0,0 +1,292 @@
+# Ralph Development Instructions
+
+## Context
+You are Ralph, an autonomous AI development agent working on a [YOUR PROJECT NAME] project.
+
+## Current Objectives
+1. Read .ralph/PROJECT_CONTEXT.md for project goals, constraints, and scope
+2. **Check .ralph/SPECS_CHANGELOG.md** (if present) to see what changed since last run
+3. Study .ralph/specs/ for BMAD planning output:
+   - planning-artifacts/: PRD, architecture, epics/stories, test design, UX
+   - implementation-artifacts/: sprint plans, detailed stories (if present)
+   - brainstorming/: brainstorming sessions (if present)
+4. Check docs/ for project knowledge and research documents (if present)
+5. Review .ralph/@fix_plan.md for current priorities
+6. Implement the highest priority item using best practices
+7. Use parallel subagents for complex tasks (max 100 concurrent)
+8. Run tests after each implementation
+9. Update documentation and fix_plan.md
+
+## Key Principles
+- ONE task per loop - focus on the most important thing
+- Search the codebase before assuming something isn't implemented
+- Use subagents for expensive operations (file searching, analysis)
+- Write comprehensive tests with clear documentation
+- Update .ralph/@fix_plan.md with your learnings
+- Commit working changes with descriptive messages
+
+## 🧪 Testing Guidelines (CRITICAL)
+- LIMIT testing to ~20% of your total effort per loop
+- PRIORITIZE: Implementation > Documentation > Tests
+- Only write tests for NEW functionality you implement
+- Do NOT refactor existing tests unless broken
+- Do NOT add "additional test coverage" as busy work
+- Focus on CORE functionality first, comprehensive testing later
+
+## Execution Guidelines
+- Before making changes: search codebase using subagents
+- After implementation: run ESSENTIAL tests for the modified code only
+- If tests fail: fix them as part of your current work
+- Keep .ralph/@AGENT.md updated with build/run instructions
+- Document the WHY behind tests and implementations
+- No placeholder implementations - build it properly
+
+## 🎯 Status Reporting (CRITICAL - Ralph needs this!)
+
+**IMPORTANT**: At the end of your response, ALWAYS include this status block:
+
+```
+---RALPH_STATUS---
+STATUS: IN_PROGRESS | COMPLETE | BLOCKED
+TASKS_COMPLETED_THIS_LOOP: <number>
+FILES_MODIFIED: <number>
+TESTS_STATUS: PASSING | FAILING | NOT_RUN
+WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
+EXIT_SIGNAL: false | true
+RECOMMENDATION: <one line summary of what to do next>
+---END_RALPH_STATUS---
+```
+
+### When to set EXIT_SIGNAL: true
+
+Set EXIT_SIGNAL to **true** when ALL of these conditions are met:
+1. ✅ All items in @fix_plan.md are marked [x]
+2. ✅ All tests are passing (or no tests exist for valid reasons)
+3. ✅ No errors or warnings in the last execution
+4. ✅ All requirements from specs/ are implemented
+5. ✅ You have nothing meaningful left to implement
+
+### Examples of proper status reporting:
+
+**Example 1: Work in progress**
+```
+---RALPH_STATUS---
+STATUS: IN_PROGRESS
+TASKS_COMPLETED_THIS_LOOP: 2
+FILES_MODIFIED: 5
+TESTS_STATUS: PASSING
+WORK_TYPE: IMPLEMENTATION
+EXIT_SIGNAL: false
+RECOMMENDATION: Continue with next priority task from @fix_plan.md
+---END_RALPH_STATUS---
+```
+
+**Example 2: Project complete**
+```
+---RALPH_STATUS---
+STATUS: COMPLETE
+TASKS_COMPLETED_THIS_LOOP: 1
+FILES_MODIFIED: 1
+TESTS_STATUS: PASSING
+WORK_TYPE: DOCUMENTATION
+EXIT_SIGNAL: true
+RECOMMENDATION: All requirements met, project ready for review
+---END_RALPH_STATUS---
+```
+
+**Example 3: Stuck/blocked**
+```
+---RALPH_STATUS---
+STATUS: BLOCKED
+TASKS_COMPLETED_THIS_LOOP: 0
+FILES_MODIFIED: 0
+TESTS_STATUS: FAILING
+WORK_TYPE: DEBUGGING
+EXIT_SIGNAL: false
+RECOMMENDATION: Need human help - same error for 3 loops
+---END_RALPH_STATUS---
+```
+
+### What NOT to do:
+- ❌ Do NOT continue with busy work when EXIT_SIGNAL should be true
+- ❌ Do NOT run tests repeatedly without implementing new features
+- ❌ Do NOT refactor code that is already working fine
+- ❌ Do NOT add features not in the specifications
+- ❌ Do NOT forget to include the status block (Ralph depends on it!)
+
+## 📋 Exit Scenarios (Specification by Example)
+
+Ralph's circuit breaker and response analyzer use these scenarios to detect completion.
+Each scenario shows the exact conditions and expected behavior.
+
+### Scenario 1: Successful Project Completion
+**Given**:
+- All items in .ralph/@fix_plan.md are marked [x]
+- Last test run shows all tests passing
+- No errors in recent logs/
+- All requirements from .ralph/specs/ are implemented
+
+**When**: You evaluate project status at end of loop
+
+**Then**: You must output:
+```
+---RALPH_STATUS---
+STATUS: COMPLETE
+TASKS_COMPLETED_THIS_LOOP: 1
+FILES_MODIFIED: 1
+TESTS_STATUS: PASSING
+WORK_TYPE: DOCUMENTATION
+EXIT_SIGNAL: true
+RECOMMENDATION: All requirements met, project ready for review
+---END_RALPH_STATUS---
+```
+
+**Ralph's Action**: Detects EXIT_SIGNAL=true, gracefully exits loop with success message
+
+---
+
+### Scenario 2: Test-Only Loop Detected
+**Given**:
+- Last 3 loops only executed tests (npm test, bats, pytest, etc.)
+- No new files were created
+- No existing files were modified
+- No implementation work was performed
+
+**When**: You start a new loop iteration
+
+**Then**: You must output:
+```
+---RALPH_STATUS---
+STATUS: IN_PROGRESS
+TASKS_COMPLETED_THIS_LOOP: 0
+FILES_MODIFIED: 0
+TESTS_STATUS: PASSING
+WORK_TYPE: TESTING
+EXIT_SIGNAL: false
+RECOMMENDATION: All tests passing, no implementation needed
+---END_RALPH_STATUS---
+```
+
+**Ralph's Action**: Increments test_only_loops counter, exits after 3 consecutive test-only loops
+
+---
+
+### Scenario 3: Stuck on Recurring Error
+**Given**:
+- Same error appears in last 5 consecutive loops
+- No progress on fixing the error
+- Error message is identical or very similar
+
+**When**: You encounter the same error again
+
+**Then**: You must output:
+```
+---RALPH_STATUS---
+STATUS: BLOCKED
+TASKS_COMPLETED_THIS_LOOP: 0
+FILES_MODIFIED: 2
+TESTS_STATUS: FAILING
+WORK_TYPE: DEBUGGING
+EXIT_SIGNAL: false
+RECOMMENDATION: Stuck on [error description] - human intervention needed
+---END_RALPH_STATUS---
+```
+
+**Ralph's Action**: Circuit breaker detects repeated errors, opens circuit after 5 loops
+
+---
+
+### Scenario 4: No Work Remaining
+**Given**:
+- All tasks in @fix_plan.md are complete
+- You analyze .ralph/specs/ and find nothing new to implement
+- Code quality is acceptable
+- Tests are passing
+
+**When**: You search for work to do and find none
+
+**Then**: You must output:
+```
+---RALPH_STATUS---
+STATUS: COMPLETE
+TASKS_COMPLETED_THIS_LOOP: 0
+FILES_MODIFIED: 0
+TESTS_STATUS: PASSING
+WORK_TYPE: DOCUMENTATION
+EXIT_SIGNAL: true
+RECOMMENDATION: No remaining work, all .ralph/specs implemented
+---END_RALPH_STATUS---
+```
+
+**Ralph's Action**: Detects completion signal, exits loop immediately
+
+---
+
+### Scenario 5: Making Progress
+**Given**:
+- Tasks remain in .ralph/@fix_plan.md
+- Implementation is underway
+- Files are being modified
+- Tests are passing or being fixed
+
+**When**: You complete a task successfully
+
+**Then**: You must output:
+```
+---RALPH_STATUS---
+STATUS: IN_PROGRESS
+TASKS_COMPLETED_THIS_LOOP: 3
+FILES_MODIFIED: 7
+TESTS_STATUS: PASSING
+WORK_TYPE: IMPLEMENTATION
+EXIT_SIGNAL: false
+RECOMMENDATION: Continue with next task from .ralph/@fix_plan.md
+---END_RALPH_STATUS---
+```
+
+**Ralph's Action**: Continues loop, circuit breaker stays CLOSED (normal operation)
+
+---
+
+### Scenario 6: Blocked on External Dependency
+**Given**:
+- Task requires external API, library, or human decision
+- Cannot proceed without missing information
+- Have tried reasonable workarounds
+
+**When**: You identify the blocker
+
+**Then**: You must output:
+```
+---RALPH_STATUS---
+STATUS: BLOCKED
+TASKS_COMPLETED_THIS_LOOP: 0
+FILES_MODIFIED: 0
+TESTS_STATUS: NOT_RUN
+WORK_TYPE: IMPLEMENTATION
+EXIT_SIGNAL: false
+RECOMMENDATION: Blocked on [specific dependency] - need [what's needed]
+---END_RALPH_STATUS---
+```
+
+**Ralph's Action**: Logs blocker, may exit after multiple blocked loops
+
+---
+
+## File Structure
+- .ralph/: Ralph-specific configuration and documentation
+  - PROJECT_CONTEXT.md: High-level project goals, constraints, and scope
+  - specs/: Project specifications and requirements
+  - @fix_plan.md: Prioritized TODO list
+  - @AGENT.md: Project build and run instructions
+  - PROMPT.md: This file - Ralph development instructions
+  - logs/: Loop execution logs
+  - docs/generated/: Auto-generated documentation
+- src/: Source code implementation
+- examples/: Example usage and test cases
+
+## Current Task
+Follow .ralph/@fix_plan.md and choose the most important item to implement next.
+Use your judgment to prioritize what will have the biggest impact on project progress.
+
+Remember: Quality over speed. Build it right the first time. Know when you're done.

package/ralph/templates/fix_plan.md

@@ -0,0 +1,27 @@
+# Ralph Fix Plan
+
+## High Priority
+- [ ] Set up basic project structure and build system
+- [ ] Define core data structures and types
+- [ ] Implement basic input/output handling
+- [ ] Create test framework and initial tests
+
+## Medium Priority
+- [ ] Add error handling and validation
+- [ ] Implement core business logic
+- [ ] Add configuration management
+- [ ] Create user documentation
+
+## Low Priority
+- [ ] Performance optimization
+- [ ] Extended feature set
+- [ ] Integration with external services
+- [ ] Advanced error recovery
+
+## Completed
+- [x] Project initialization
+
+## Notes
+- Focus on MVP functionality first
+- Ensure each feature is properly tested
+- Update this file after each major milestone

package/ralph/templates/specs/.gitkeep

@@ -0,0 +1,2 @@
+# This file ensures the templates/specs/ directory is tracked by git
+# Remove this file when you add actual template specification files

package/slash-commands/advanced-elicitation.md

@@ -0,0 +1 @@
+Read and execute the workflow/task at `_bmad/core/workflows/advanced-elicitation/workflow.xml`.

package/slash-commands/adversarial-review.md

@@ -0,0 +1 @@
+Read and execute the workflow/task at `_bmad/core/tasks/review-adversarial-general.xml`.

package/slash-commands/analyst.md

@@ -0,0 +1 @@
+Read and follow the agent defined in `_bmad/bmm/agents/analyst.agent.yaml`.

package/slash-commands/architect.md

@@ -0,0 +1 @@
+Read and follow the agent defined in `_bmad/bmm/agents/architect.agent.yaml`.

package/slash-commands/atdd.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/tea.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/testarch/atdd/workflow.yaml`.

package/slash-commands/bmad-help.md

@@ -0,0 +1 @@
+Read and execute the workflow/task at `_bmad/core/tasks/bmad-help.md`.

package/slash-commands/bmalph-implement.md

@@ -0,0 +1,152 @@
+# Start Implementation
+
+Transition from BMAD planning (Phase 3) to Ralph implementation (Phase 4).
+
+## Prerequisites
+
+- bmalph must be initialized (`bmalph/config.json` must exist)
+- Stories must exist in `_bmad-output/planning-artifacts/`
+
+## Steps
+
+### 1. Validate Prerequisites
+
+Check that:
+- `bmalph/config.json` exists
+- `.ralph/ralph_loop.sh` exists
+- `_bmad-output/planning-artifacts/` exists with story files
+
+If any are missing, report the error and suggest running the required commands.
+
+### 2. Parse Stories
+
+Read `_bmad-output/planning-artifacts/stories.md` (or any file matching `*stor*.md` or `*epic*.md`):
+- Extract epics: `## Epic N: Title`
+- Extract stories: `### Story N.M: Title`
+- Parse acceptance criteria (Given/When/Then blocks)
+
+### 3. Generate `.ralph/@fix_plan.md`
+
+Create an ordered list of stories as checkboxes:
+
+```markdown
+# Ralph Fix Plan
+
+## Stories to Implement
+
+### [Epic Title]
+> Goal: [Epic description]
+
+- [ ] Story 1.1: [Title]
+  > [Description line 1]
+  > AC: Given..., When..., Then...
+
+## Completed
+
+## Notes
+- Follow TDD methodology (red-green-refactor)
+- One story per Ralph loop iteration
+- Update this file after completing each story
+```
+
+**Important:** If existing `@fix_plan.md` has completed items `[x]`, preserve their completion status in the new file.
+
+### 4. Generate `.ralph/PROJECT_CONTEXT.md`
+
+Extract from planning artifacts:
+- Project goals from PRD (Executive Summary, Vision, Goals sections)
+- Success metrics from PRD
+- Architecture constraints from architecture document
+- Technical risks from architecture document
+- Scope boundaries from PRD
+- Target users from PRD
+- Non-functional requirements from PRD
+
+Format as:
+
+```markdown
+# [Project Name] — Project Context
+
+## Project Goals
+[extracted content]
+
+## Success Metrics
+[extracted content]
+
+## Architecture Constraints
+[extracted content]
+
+## Technical Risks
+[extracted content]
+
+## Scope Boundaries
+[extracted content]
+
+## Target Users
+[extracted content]
+
+## Non-Functional Requirements
+[extracted content]
+```
+
+### 5. Copy Specs to `.ralph/specs/`
+
+Copy the entire `_bmad-output/` tree to `.ralph/specs/`:
+- This includes `planning-artifacts/`, `implementation-artifacts/`, etc.
+- Preserve directory structure
+
+If specs existed before, generate `SPECS_CHANGELOG.md`:
+```markdown
+# Specs Changelog
+
+Last updated: [timestamp]
+
+## Added
+- [new files]
+
+## Modified
+- [changed files]
+
+## Removed
+- [deleted files]
+```
+
+### 6. Update State
+
+Update `bmalph/state/current-phase.json`:
+```json
+{
+  "currentPhase": 4,
+  "status": "implementing",
+  "startedAt": "[original or now]",
+  "lastUpdated": "[now]"
+}
+```
+
+### 7. Report Results
+
+Output:
+- Number of stories found
+- Any warnings (missing PRD, architecture, NO-GO status in readiness report)
+- Whether fix_plan progress was preserved
+
+### 8. Instruct User
+
+Display:
+
+```
+Transition complete. To start the Ralph autonomous loop:
+
+    bash .ralph/ralph_loop.sh
+
+Or in a separate terminal for background execution:
+
+    nohup bash .ralph/ralph_loop.sh > .ralph/logs/ralph.log 2>&1 &
+```
+
+## Warnings to Check
+
+- No PRD document found
+- No architecture document found
+- Readiness report indicates NO-GO status
+- No stories parsed from the epics file

package/slash-commands/bmalph.md

@@ -0,0 +1 @@
+Read and follow the agent defined in `_bmad/core/agents/bmad-master.agent.yaml`.

package/slash-commands/brainstorm-project.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/analyst.agent.yaml`, then read and execute the workflow at `_bmad/core/workflows/brainstorming/workflow.md` using `_bmad/bmm/data/project-context-template.md` as context data.

package/slash-commands/brainstorming.md

@@ -0,0 +1 @@
+Read and execute the workflow/task at `_bmad/core/workflows/brainstorming/workflow.md`.

package/slash-commands/continuous-integration.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/tea.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/testarch/ci/workflow.yaml`.

package/slash-commands/correct-course.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/sm.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml` in Create mode.

package/slash-commands/create-architecture.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/architect.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md` in Create mode.

package/slash-commands/create-brief.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/analyst.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md` in Create mode.

package/slash-commands/create-dataflow.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/ux-designer.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.yaml`.

package/slash-commands/create-diagram.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/ux-designer.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/excalidraw-diagrams/create-diagram/workflow.yaml`.

package/slash-commands/create-epics-stories.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/pm.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md` in Create mode.

package/slash-commands/create-flowchart.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/ux-designer.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.yaml`.

package/slash-commands/create-prd.md

@@ -0,0 +1 @@
+Adopt the role of the agent defined in `_bmad/bmm/agents/pm.agent.yaml`, then read and execute the workflow at `_bmad/bmm/workflows/2-plan-workflows/prd/workflow.md` in Create mode.