npm - aiwf - Versions diffs - 0.3.22 → 0.4.0 - Mend

aiwf 0.3.22 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (456) hide show

package/docs/ADR_MANAGEMENT_GUIDE.md DELETED Viewed

@@ -1,602 +0,0 @@
-# AIWF Architecture Decision Record (ADR) Management Guide
-> A comprehensive guide to managing architectural decisions using ADRs in AIWF projects
-[한국어](ADR_MANAGEMENT_GUIDE.ko.md) | [English](ADR_MANAGEMENT_GUIDE.md)
-## Table of Contents
-1. [What are ADRs?](#what-are-adrs)
-2. [Why Use ADRs in AIWF?](#why-use-adrs-in-aiwf)
-3. [ADR Structure](#adr-structure)
-4. [Integration with AIWF](#integration-with-aiwf)
-5. [Creating ADRs](#creating-adrs)
-6. [Managing ADRs](#managing-adrs)
-7. [ADR Templates](#adr-templates)
-8. [Best Practices](#best-practices)
-9. [Automation and Tools](#automation-and-tools)
-10. [Examples](#examples)
-## What are ADRs?
-Architecture Decision Records (ADRs) are short text documents that capture important architectural decisions made in a project, along with their context and consequences. They serve as a historical record of why certain decisions were made and help future developers understand the reasoning behind architectural choices.
-### Key Characteristics
-- **Immutable**: Once written, ADRs should not be changed (only superseded)
-- **Numbered**: Sequential numbering for easy reference
-- **Context-Rich**: Includes the situation that led to the decision
-- **Consequence-Aware**: Documents the results and trade-offs
-## Why Use ADRs in AIWF?
-### Benefits for AI-Assisted Development
-1. **AI Context**: Provides Claude Code with historical context for decisions
-2. **Autonomous Guidance**: Helps YOLO mode make informed architectural choices
-3. **Consistency**: Ensures AI follows established architectural patterns
-4. **Documentation**: Maintains architectural knowledge across development sessions
-### AIWF-Specific Advantages
-- **Sprint Planning**: ADRs inform task creation and priority
-- **Persona Context**: Different AI personas can reference relevant decisions
-- **Quality Control**: Engineering Guard can validate compliance with decisions
-- **Recovery**: Checkpoint system can reference ADRs for context restoration
-## ADR Structure
-### Standard ADR Format
-```markdown
-# ADR-001: Decision Title
-**Date**: YYYY-MM-DD
-**Status**: [Proposed | Accepted | Deprecated | Superseded]
-**Context**: AIWF Project Context
-## Context
-Description of the issue or situation that prompted this decision.
-## Decision
-The architectural decision that was made.
-## Consequences
-### Positive
-- Benefits and advantages of this decision
-### Negative
-- Drawbacks and trade-offs
-### Neutral
-- Other effects and considerations
-## Implementation Notes
-Specific guidance for implementation within AIWF.
-## Related Decisions
-- Links to related ADRs
-- References to AIWF components affected
-## Compliance Validation
-- How to verify adherence to this decision
-- Engineering Guard rules if applicable
-```
-### AIWF-Enhanced Structure
-```markdown
-# ADR-001: Decision Title
-**Date**: YYYY-MM-DD
-**Status**: Accepted
-**Context**: AIWF v0.3.16+ Project
-**Affects**: [CLI | YOLO | Personas | Templates]
-**Persona Relevance**: [architect | developer | security]
-## Context
-[Standard context section]
-## Decision
-[Standard decision section]
-## AIWF Integration
-### CLI Impact
-How this decision affects CLI commands and workflows.
-### YOLO Mode Considerations
-Implications for autonomous execution and safety mechanisms.
-### Persona Guidelines
-Specific guidance for different AI personas.
-### Template Updates
-Required changes to project templates.
-## Consequences
-[Standard consequences section]
-## Validation Rules
-### Engineering Guard Rules
-```yaml
-# .aiwf/yolo-config.yaml additions
-custom_rules:
-  - name: "ADR-001 Compliance"
-    pattern: "validation_pattern"
-    severity: "warning"
-```
-### Automated Checks
-- Unit tests to validate compliance
-- CI/CD pipeline validations
-- AIWF command integrations
-## Implementation Guide
-### Step-by-Step Implementation
-1. [Detailed implementation steps]
-2. [AIWF-specific considerations]
-3. [Validation checkpoints]
-### Code Examples
-```javascript
-// Implementation examples
-```
-## Related Documents
-- [Link to relevant AIWF documentation]
-- [Related ADRs]
-- [AIWF module documentation]
-```
-## Integration with AIWF
-### Directory Structure
-```
-.aiwf/
-├── adrs/
-│   ├── 0001-module-architecture.md
-│   ├── 0002-yolo-safety-mechanisms.md
-│   ├── 0003-persona-selection-strategy.md
-│   └── template.md
-├── yolo-config.yaml
-└── state.json
-```
-### AIWF Command Integration
-#### Planned Commands (Future Enhancement)
-```bash
-# Create new ADR
-aiwf adr create "Database Migration Strategy"
-# List ADRs
-aiwf adr list
-# Show specific ADR
-aiwf adr show 001
-# Link ADR to current work
-aiwf adr link 001 --to-task T001
-# Validate current code against ADRs
-aiwf adr validate
-```
-### Claude Code Integration
-#### ADR-Aware Commands
-```markdown
-# In Claude Code
-/aiwf_prime  # Now includes ADR context loading
-/aiwf_create_milestone_plan  # References relevant ADRs
-/aiwf_yolo  # Considers ADR constraints
-```
-## Creating ADRs
-### When to Create an ADR
-1. **Major Architectural Changes**: Database schema, API design, module structure
-2. **Technology Choices**: Framework selection, library adoption, tool integration
-3. **AIWF-Specific Decisions**: YOLO behavior, persona configuration, template design
-4. **Security Decisions**: Authentication, authorization, data protection
-5. **Performance Decisions**: Caching strategies, optimization approaches
-### Creation Process
-#### Manual Creation
-```bash
-# 1. Copy template
-cp .aiwf/adrs/template.md .aiwf/adrs/0001-your-decision.md
-# 2. Edit the ADR
-vim .aiwf/adrs/0001-your-decision.md
-# 3. Link to current work
-# Add ADR reference to task or sprint documentation
-# 4. Commit
-git add .aiwf/adrs/0001-your-decision.md
-git commit -m "docs: add ADR-001 for your decision"
-```
-#### Using AIWF (Future)
-```bash
-# Create from template
-aiwf adr create "Microservices Communication Pattern"
-# Create with context
-aiwf adr create "YOLO Safety Mechanism" --context="yolo-mode"
-# Create from persona perspective
-aiwf adr create "Security Policy" --persona="security"
-```
-## Managing ADRs
-### Lifecycle Management
-#### Status Transitions
-```
-Proposed → Accepted → [Deprecated | Superseded]
-    ↓
- Rejected
-```
-#### Updating Status
-```markdown
-# To deprecate an ADR
-## Status Update
-**Previous Status**: Accepted
-**New Status**: Deprecated
-**Date**: 2025-01-27
-**Reason**: Superseded by ADR-015
-```
-### Linking and References
-#### Task Integration
-```markdown
-# In task files
-## Architectural Context
-- ADR-001: Module Architecture Pattern
-- ADR-003: API Design Principles
-## Compliance Requirements
-- Follow ADR-001 module structure
-- Implement ADR-003 error handling
-```
-#### Sprint Planning
-```markdown
-# In sprint documentation
-## Architectural Decisions to Consider
-- [ ] Review ADR-002 for database access patterns
-- [ ] Apply ADR-004 security guidelines
-- [ ] Validate against ADR-001 module structure
-```
-## ADR Templates
-### Basic Template
-```markdown
-# ADR-{NUMBER}: {TITLE}
-**Date**: {DATE}
-**Status**: Proposed
-**Context**: AIWF Project
-## Context
-What is the issue we're facing? What factors are relevant?
-## Decision
-What is the change we're making?
-## Consequences
-What becomes easier or more difficult as a result?
-```
-### AIWF-Specific Template
-```markdown
-# ADR-{NUMBER}: {TITLE}
-**Date**: {DATE}
-**Status**: Proposed
-**Context**: AIWF v{VERSION}+ Project
-**Affects**: [CLI | YOLO | Personas | Templates | Core]
-**Persona Relevance**: [architect | developer | security | tester]
-## Context
-### Problem Statement
-[Description of the architectural challenge]
-### AIWF Context
-[How this relates to AIWF workflows and components]
-### Constraints
-[Technical, business, or project constraints]
-## Decision
-### Chosen Approach
-[The architectural decision made]
-### Alternatives Considered
-[Other options that were evaluated]
-### Rationale
-[Why this decision was made]
-## AIWF Integration
-### CLI Impact
-[How this affects command-line operations]
-### YOLO Mode Considerations
-[Implications for autonomous execution]
-### Persona Guidelines
-[Guidance for different AI personas]
-### Template Changes
-[Required updates to project templates]
-## Consequences
-### Positive
-- [Benefits and improvements]
-### Negative
-- [Trade-offs and limitations]
-### Neutral
-- [Other effects]
-## Implementation
-### Action Items
-- [ ] [Specific implementation steps]
-- [ ] [AIWF configuration updates]
-- [ ] [Documentation updates]
-### Validation
-[How to verify correct implementation]
-### Timeline
-[Implementation schedule if applicable]
-## Compliance
-### Engineering Guard Rules
-```yaml
-# Additional rules for .aiwf/yolo-config.yaml
-adr_compliance:
-  adr_{NUMBER}:
-    enabled: true
-    severity: warning
-    pattern: "{validation_pattern}"
-```
-### Automated Checks
-[Unit tests, CI/CD validations, etc.]
-## Related Documents
-- [Links to relevant documentation]
-- [Related ADRs]
-- [AIWF module references]
-## Review and Approval
-### Reviewers
-- [ ] Architect: {NAME}
-- [ ] Lead Developer: {NAME}
-- [ ] Security Lead: {NAME} (if security-related)
-### Approval Date
-[Date when ADR was accepted]
-```
-## Best Practices
-### Writing Effective ADRs
-1. **Be Concise**: Keep ADRs focused and readable
-2. **Be Specific**: Avoid vague language and generalities
-3. **Include Context**: Explain the situation that led to the decision
-4. **Document Trade-offs**: Be honest about consequences
-5. **Link to Code**: Reference specific implementations
-### AIWF-Specific Best Practices
-1. **Persona Alignment**: Consider how different personas will interpret the ADR
-2. **YOLO Compatibility**: Ensure decisions work with autonomous execution
-3. **Template Integration**: Update project templates to reflect decisions
-4. **Engineering Guard Rules**: Add validation rules where applicable
-5. **Sprint Planning**: Reference ADRs in task and sprint documentation
-### Maintenance Practices
-1. **Regular Reviews**: Periodically review and update ADR status
-2. **Link Validation**: Ensure references remain accurate
-3. **Implementation Tracking**: Monitor compliance with decisions
-4. **Knowledge Transfer**: Use ADRs for onboarding new team members
-## Automation and Tools
-### Git Hooks Integration
-```bash
-# .git/hooks/pre-commit
-#!/bin/bash
-# Validate ADR references in commit messages
-if git log -1 --pretty=%B | grep -q "ADR-[0-9]"; then
-    echo "✅ ADR reference found in commit message"
-else
-    echo "ℹ️  Consider referencing relevant ADRs in commit message"
-fi
-```
-### Future AIWF Integration
-#### Planned Features
-- **ADR Command**: `aiwf adr` command suite
-- **Context Loading**: Automatic ADR context in Claude Code
-- **Validation**: Engineering Guard ADR compliance checks
-- **Templates**: ADR-aware project templates
-#### Proposed Workflow
-```bash
-# 1. Create ADR with AIWF
-aiwf adr create "API Rate Limiting Strategy"
-# 2. Link to current work
-aiwf task link ADR-001 --to-current
-# 3. Validate implementation
-aiwf adr validate --against=ADR-001
-# 4. Generate compliance report
-aiwf adr report --sprint=S01
-```
-## Examples
-### Example 1: Module Architecture ADR
-```markdown
-# ADR-001: Modular Component Architecture
-**Date**: 2025-01-27
-**Status**: Accepted
-**Context**: AIWF v0.3.16+ Project
-**Affects**: Core, CLI, Templates
-**Persona Relevance**: architect, developer
-## Context
-AIWF grew organically and components became tightly coupled, making it difficult to test, maintain, and extend individual features.
-## Decision
-Adopt a modular architecture with clear dependency boundaries:
-- Core utilities (paths, messages, language-utils)
-- Feature modules (persona, checkpoint, compression)
-- Plugin system for extensions
-## AIWF Integration
-### CLI Impact
-Commands will load modules dynamically based on functionality needed.
-### YOLO Mode Considerations
-Modular design allows YOLO to load only necessary components, improving performance.
-### Engineering Guard Rules
-```yaml
-module_architecture:
-  enforce_boundaries: true
-  max_dependencies: 5
-  circular_dependency_check: true
-```
-## Consequences
-### Positive
-- Improved testability and maintainability
-- Faster development cycles
-- Better plugin support
-### Negative
-- Increased initial complexity
-- Need for dependency management
-## Implementation
-- Refactor existing monolithic components
-- Implement dependency injection
-- Update documentation and templates
-```
-### Example 2: YOLO Safety Mechanism ADR
-```markdown
-# ADR-002: YOLO Safety Mechanism Framework
-**Date**: 2025-01-27
-**Status**: Accepted
-**Context**: AIWF v0.3.16+ YOLO Mode
-**Affects**: YOLO, Engineering Guard, Checkpoint
-**Persona Relevance**: architect, security
-## Context
-Autonomous execution needs robust safety mechanisms to prevent data loss, security issues, and code quality degradation.
-## Decision
-Implement multi-layered safety framework:
-1. Engineering Guard for code quality
-2. Checkpoint system for recovery
-3. Breakpoint system for critical operations
-4. Real-time monitoring and intervention
-## YOLO Mode Considerations
-The safety framework is specifically designed for autonomous execution:
-- Non-blocking quality checks
-- Automatic rollback on failures
-- Progressive escalation of interventions
-## Engineering Guard Rules
-```yaml
-yolo_safety:
-  critical_file_protection: true
-  test_failure_threshold: 10
-  complexity_monitoring: true
-  automatic_checkpoints: 5
-```
-## Implementation
-- Deploy engineering-guard.js with YOLO templates
-- Integrate checkpoint-manager.js with session tracking
-- Add safety configuration to yolo-config.yaml
-```
-## Related Commands
-### Current AIWF Commands
-- `/aiwf_prime` - Load project context (can include ADR context)
-- `/aiwf_create_milestone_plan` - Reference ADRs in planning
-- `/aiwf_do_task` - Consider ADR constraints during implementation
-### Planned Commands
-- `aiwf adr create` - Create new ADR
-- `aiwf adr list` - List all ADRs
-- `aiwf adr validate` - Validate code against ADRs
-- `aiwf adr link` - Link ADRs to tasks
-## Related Documents
-- [ARCHITECTURE.md](ARCHITECTURE.md) - Overall system architecture
-- [MODULE_MANAGEMENT_GUIDE.md](MODULE_MANAGEMENT_GUIDE.md) - Module dependency management
-- [YOLO_SYSTEM_GUIDE.md](YOLO_SYSTEM_GUIDE.md) - YOLO mode documentation
-- [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md) - Development practices
----
-**Last Updated**: 2025-01-27
-**Version**: Compatible with AIWF v0.3.16+
-**Status**: Documentation Framework (ADR commands to be implemented)