agentic-code 0.5.1

package/.agents/rules/core/ai-development-guide.md

@@ -0,0 +1,272 @@
+# AI Developer Guide
+
+## Technical Anti-patterns (Red Flag Patterns)
+
+Immediately stop and reconsider design when detecting the following patterns:
+
+### Code Quality Anti-patterns
+1. **Writing similar code 3 or more times**
+2. **Multiple responsibilities mixed in a single file**
+3. **Defining same content in multiple files**
+4. **Making changes without checking dependencies**
+5. **Disabling code with comments**
+6. **Error suppression**
+
+### Design Anti-patterns
+- **"Make it work for now" thinking**
+- **Patchwork implementation**
+- **Optimistic implementation of uncertain technology**
+- **Symptomatic fixes**
+- **Unplanned large-scale changes**
+
+## Fail-Fast Fallback Design Principles
+
+### Core Principle
+Prioritize primary code reliability over fallback implementations. In distributed systems, excessive fallback mechanisms can mask errors and make debugging difficult.
+
+### Implementation Guidelines
+
+#### Default Approach
+- **Explicit failure over silent defaults**: Errors must be visible and traceable, not masked by automatic default values
+- **Preserve error context**: Include original error information when re-throwing
+
+#### When Fallbacks Are Acceptable
+- **Only with explicit Design Doc approval**: Document why fallback is necessary
+- **Business-critical continuity**: When partial functionality is better than none
+- **Graceful degradation paths**: Clearly defined degraded service levels
+
+#### Layer Responsibilities
+- **Infrastructure Layer**:
+  - Always throw errors upward
+  - No business logic decisions
+  - Provide detailed error context
+
+- **Application Layer**:
+  - Make business-driven error handling decisions
+  - Implement fallbacks only when specified in requirements
+  - Log all fallback activations for monitoring
+
+### Error Masking Detection
+
+**Review Triggers** (require design review):
+- Writing 3rd error handling block in the same feature
+- Multiple error handling structures in single function
+- Nested error handling structures
+- Error handlers that return default values without propagating
+
+**Before Implementing Any Fallback**:
+1. Verify Design Doc explicitly defines this fallback
+2. Document the business justification
+3. Ensure error is logged with full context
+4. Add monitoring/alerting for fallback activation
+
+### Implementation Patterns
+
+Note: Use your language's standard error handling mechanism (exceptions, Result types, error values, etc.)
+
+```
+❌ AVOID: Silent fallback that hides errors
+    [handle error]:
+        return DEFAULT_USER  // Error is hidden, debugging becomes difficult
+
+✅ PREFERRED: Explicit failure with context
+    [handle error]:
+        logError('Failed to fetch user data', userId, error)
+        propagate ServiceError('User data unavailable', error)
+
+✅ ACCEPTABLE: Documented fallback with monitoring (when justified in Design Doc)
+    [handle error]:
+        // Fallback defined in Design Doc section 3.2.1
+        logWarning('Primary data source failed, using cache', error)
+        incrementMetric('data.fallback.cache_used')
+
+        cachedData = fetchFromCache()
+        if not cachedData:
+            propagate ServiceError('Both primary and cache failed', error)
+        return cachedData
+```
+
+## Rule of Three - Criteria for Code Duplication
+
+| Duplication Count | Action | Reason |
+|-------------------|--------|--------|
+| 1st time | Inline implementation | Cannot predict future changes |
+| 2nd time | Consider future consolidation | Pattern beginning to emerge |
+| 3rd time | Implement commonalization | Pattern established |
+
+### Criteria for Commonalization
+
+**Cases for Commonalization**
+- Business logic duplication
+- Complex processing algorithms
+- Areas likely requiring bulk changes
+- Validation rules
+
+**Cases to Avoid Commonalization**
+- Accidental matches (coincidentally same code)
+- Possibility of evolving in different directions
+- Significant readability decrease from commonalization
+- Simple helpers in test code
+
+### Implementation Example
+```
+// ❌ Bad: Immediate commonalization on 1st duplication
+function validateUserEmail(email) { /* ... */ }
+function validateContactEmail(email) { /* ... */ }
+// → Premature abstraction
+
+// ✅ Good: Commonalize on 3rd occurrence
+// 1st time: inline implementation
+// 2nd time: Copy but consider future
+// 3rd time: Extract to common validator
+function validateEmail(email, context) { /* ... */ }
+```
+
+## Common Failure Patterns and Avoidance Methods
+
+### Pattern 1: Error Fix Chain
+**Symptom**: Fixing one error causes new errors
+**Cause**: Surface-level fixes without understanding root cause
+**Avoidance**: Identify root cause with 5 Whys before fixing
+
+### Pattern 2: Implementation Without Sufficient Testing
+**Symptom**: Many bugs after implementation
+**Cause**: Ignoring Red-Green-Refactor process
+**Avoidance**: Always start with failing tests
+
+### Pattern 4: Ignoring Technical Uncertainty
+**Symptom**: Frequent unexpected errors when introducing new technology
+**Cause**: Assuming "it should work according to official documentation" without prior investigation
+**Avoidance**:
+- Record certainty evaluation at the beginning of task files
+  ```
+  Certainty: low (Reason: no examples of MCP connection found)
+  Exploratory implementation: true
+  Fallback: use conventional API
+  ```
+- For low certainty cases, create minimal verification code first
+
+### Pattern 5: Insufficient Existing Code Investigation
+**Symptom**: Duplicate implementations, architecture inconsistency, integration failures
+**Cause**: Insufficient understanding of existing code before implementation
+**Avoidance Methods**:
+- Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords)
+- Similar functionality found → Use that implementation (do not create new implementation)
+- Similar functionality is technical debt → Create ADR improvement proposal before implementation
+- No similar functionality exists → Implement new functionality following existing design philosophy
+- Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
+
+## Debugging Techniques
+
+### 1. Error Analysis Procedure
+```bash
+# How to read stack traces
+1. Read error message (first line) accurately
+2. Focus on first and last of stack trace
+3. Identify first line where your code appears
+```
+
+### 2. 5 Whys - Root Cause Analysis
+```
+Symptom: Application crash on startup
+Why1: Configuration loading failed → Why2: Config file format changed
+Why3: Dependency update → Why4: Library breaking change
+Why5: Unconstrained dependency version specification
+Root cause: Inappropriate version management strategy
+```
+
+### 3. Minimal Reproduction Code
+To isolate problems, attempt reproduction with minimal code:
+- Remove unrelated parts
+- Replace external dependencies with mocks
+- Create minimal configuration that reproduces problem
+
+### 4. Debug Log Output
+```
+// Track problems with structured logs
+log('DEBUG:', {
+  context: 'user-creation',
+  input: { email, name },
+  state: currentState,
+  timestamp: currentTimestamp()
+})
+```
+
+## Situations Requiring Technical Decisions
+
+### Timing of Abstraction
+- Extract patterns after writing concrete implementation 3 times
+- Be conscious of YAGNI, implement only currently needed features
+- Prioritize current simplicity over future extensibility
+
+### Performance vs Readability
+- Prioritize readability unless clear bottleneck exists
+- Measure before optimizing (don't guess, measure)
+- Document reason with comments when optimizing
+
+## Continuous Improvement Mindset
+
+- **Humility**: Perfect code doesn't exist, welcome feedback
+- **Courage**: Execute necessary refactoring boldly
+- **Transparency**: Clearly document technical decision reasoning
+
+## Implementation Completeness Assurance
+
+### Impact Analysis: Mandatory 3-Stage Process
+
+Complete these stages sequentially before any implementation:
+
+**1. Discovery** - Identify all affected code:
+- Implementation references (imports, calls, instantiations)
+- Interface dependencies (contracts, types, data structures)
+- Test coverage
+- Configuration (build configs, env settings, feature flags)
+- Documentation (comments, docs, diagrams)
+
+**2. Understanding** - Analyze each discovered location:
+- Role and purpose in the system
+- Dependency direction (consumer or provider)
+- Data flow (origin → transformations → destination)
+- Coupling strength
+
+**3. Identification** - Produce structured report:
+```
+## Impact Analysis
+### Direct Impact
+- [Unit]: [Reason and modification needed]
+
+### Indirect Impact
+- [System]: [Integration path → reason]
+
+### Data Flow
+[Source] → [Transformation] → [Consumer]
+
+### Risk Assessment
+- High: [Complex dependencies, fragile areas]
+- Medium: [Moderate coupling, test gaps]
+- Low: [Isolated, well-tested areas]
+
+### Implementation Order
+1. [Start with lowest risk or deepest dependency]
+2. [...]
+```
+
+**Critical**: Do not implement until all 3 stages are documented
+
+**Relationship to Pattern 5**: This process provides the structured methodology to avoid "Insufficient Existing Code Investigation" (see .agents/rules/core/ai-development-guide.md:150-158)
+
+### Unused Code Deletion
+
+When unused code is detected:
+- Will it be used in this work? Yes → Implement now | No → Delete now (Git preserves)
+- Applies to: Code, tests, docs, configs, assets
+
+### Existing Code Modification
+
+```
+In use? No → Delete
+       Yes → Working? No → Delete + Reimplement
+                     Yes → Fix/Extend
+```
+
+**Principle**: Prefer clean implementation over patching broken code

package/.agents/rules/core/documentation-criteria.md

@@ -0,0 +1,184 @@
+# Documentation Creation Criteria
+
+## Creation Decision Matrix
+
+| Condition | Required Documents | Creation Order |
+|-----------|-------------------|----------------|
+| New Feature Addition | PRD → [ADR] → Design Doc → Work Plan | After PRD approval |
+| ADR Conditions Met (see below) | ADR → Design Doc → Work Plan | Start immediately |
+| 6+ Files | ADR → Design Doc → Work Plan (Required) | Start immediately |
+| 3-5 Files | Design Doc → Work Plan (Recommended) | Start immediately |
+| 1-2 Files | None | Direct implementation |
+
+## ADR Creation Conditions (Required if Any Apply)
+
+### 1. Type System Changes
+- **Adding nested types/structures with 3+ levels**: e.g., `A { B { C { D } } }`
+  - Rationale: Deep nesting has high complexity and wide impact scope
+- **Changing/deleting types used in 3+ locations**
+  - Rationale: Multiple location impacts require careful consideration
+- **Data representation responsibility changes** (e.g., transfer object→domain model)
+  - Rationale: Conceptual model changes affect design philosophy
+
+### 2. Data Flow Changes
+- **Storage location changes** (DB→File, Memory→Cache)
+- **Processing order changes with 3+ steps**
+  - Example: "Input→Validation→Save" to "Input→Save→Async Validation"
+- **Data passing method changes** (props→Context, direct reference→events)
+
+### 3. Architecture Changes
+- Layer addition, responsibility changes, component relocation
+
+### 4. External Dependency Changes
+- Library/framework/external API introduction or replacement
+
+### 5. Complex Implementation Logic (Regardless of Scale)
+- Managing 3+ states
+- Coordinating 5+ asynchronous processes
+
+## Detailed Document Definitions
+
+### PRD (Product Requirements Document)
+
+**Purpose**: Define business requirements and user value
+
+**Includes**:
+- Business requirements and user value
+- Success metrics and KPIs (measurable format)
+- User stories and use cases
+- MoSCoW prioritization (Must/Should/Could/Won't)
+- MVP and Future phase separation
+- User journey diagram
+- Scope boundary diagram
+
+**Excludes**:
+- Technical implementation details (→Design Doc)
+- Technical selection rationale (→ADR)
+- **Implementation phases** (→Work Plan)
+- **Task breakdown** (→Work Plan)
+
+### ADR (Architecture Decision Record)
+
+**Purpose**: Record technical decisions
+
+**Includes**:
+- Decision (what was selected)
+- Rationale (why that selection was made)
+- Option comparison (minimum 3 options) and trade-offs
+- Architecture impact
+- Principled implementation guidelines
+
+**Excludes**:
+- Implementation schedule, duration (→Work Plan)
+- Detailed implementation procedures (→Design Doc)
+- Specific code examples (→Design Doc)
+- Resource assignments (→Work Plan)
+
+### Design Document
+
+**Purpose**: Define technical implementation
+
+**Includes**:
+- **Existing codebase analysis** (required)
+  - Implementation path mapping (both existing and new)
+  - Integration point clarification (connection points with existing code even for new implementations)
+- Technical implementation approach (vertical/horizontal/hybrid)
+- **Technical dependencies and implementation constraints** (required implementation order)
+- Interface and type definitions
+- Data flow and component design
+- **E2E verification procedures at integration points**
+- **Acceptance criteria (measurable format)**
+- Change impact map (clearly specify direct impact/indirect impact/no ripple effect)
+- Complete enumeration of integration points
+- Data contract clarification
+- **Agreement checklist** (agreements with stakeholders)
+- **Prerequisite ADRs** (including common ADRs)
+
+**Required Structural Elements**:
+```yaml
+Change Impact Map:
+  Change Target: [Component/Feature]
+  Direct Impact: [Files/Functions]
+  Indirect Impact: [Data format/Processing time]
+  No Ripple Effect: [Unaffected features]
+
+API Contract Change Matrix:
+  Existing: [Function/operation signature]
+  New: [Function/operation signature]
+  Conversion Required: [Yes/No]
+  Compatibility Strategy: [Approach]
+```
+
+**Excludes**:
+- Why that technology was chosen (→Reference ADR)
+- When to implement, duration (→Work Plan)
+- Who will implement (→Work Plan)
+
+### Work Plan
+
+**Purpose**: Implementation task management and progress tracking
+
+**Includes**:
+- Task breakdown and dependencies (maximum 2 levels)
+- Schedule and duration estimates
+- **Copy E2E verification procedures from Design Doc** (cannot delete, can add)
+- **Stage 4 Quality Assurance Stage (required)**
+- Progress records (checkbox format)
+
+**Excludes**:
+- Technical rationale (→ADR)
+- Design details (→Design Doc)
+
+**Stage Division Criteria**:
+1. **Stage 1: Foundation Implementation** - Type definitions, interfaces, test preparation
+2. **Stage 2: Core Feature Implementation** - Business logic, unit tests
+3. **Stage 3: Integration Implementation** - External connections, presentation layer
+4. **Stage 4: Quality Assurance (Required)** - Acceptance criteria achievement, all tests passing, quality checks
+
+**Three Elements of Task Completion Definition**:
+1. **Implementation Complete**: Code is functional
+2. **Quality Complete**: Tests, type checks, linting pass
+3. **Integration Complete**: Verified connection with other components
+
+## Creation Process
+
+1. **Problem Analysis**: Change scale assessment, ADR condition check
+2. **ADR Option Consideration** (ADR only): Compare 3+ options, specify trade-offs
+3. **Creation**: Use templates, include measurable conditions
+4. **Approval**: "Accepted" after review enables implementation
+
+## Storage Locations
+
+| Document | Path | Naming Convention | Template |
+|----------|------|------------------|----------|
+| PRD | `docs/prd/` | `[feature-name]-prd.md` | `template-en.md` |
+| ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` | `template-en.md` |
+| Design Doc | `docs/design/` | `[feature-name]-design.md` | `template-en.md` |
+| Work Plan | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | `template-en.md` |
+
+*Note: Work plans are stored in `docs/plans/` and excluded by `.gitignore`
+
+## ADR Status
+`Proposed` → `Accepted` → `Deprecated`/`Superseded`/`Rejected`
+
+## AI Automation Rules
+- 5+ files: Suggest ADR creation
+- Type/data flow change detected: ADR mandatory
+- Check existing ADRs before implementation
+
+## Diagram Requirements
+
+Required diagrams for each document (using mermaid notation):
+
+| Document | Required Diagrams | Purpose |
+|----------|------------------|---------|
+| PRD | User journey diagram, Scope boundary diagram | Clarify user experience and scope |
+| ADR | Option comparison diagram (when needed) | Visualize trade-offs |
+| Design Doc | Architecture diagram, Data flow diagram | Understand technical structure |
+| Work Plan | Phase structure diagram, Task dependency diagram | Clarify implementation order |
+
+## Common ADR Relationships
+1. **At creation**: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
+2. **When missing**: Consider creating necessary common ADRs
+3. **Design Doc**: Specify common ADRs in "Prerequisite ADRs" section
+4. **Compliance check**: Verify design aligns with common ADR decisions

package/.agents/rules/core/integration-e2e-testing.md

@@ -0,0 +1,76 @@
+# Integration Test & E2E Test Design/Implementation Rules
+
+## Test Types and Limits
+
+| Type | Purpose | Limit |
+|------|---------|-------|
+| Integration Test | Component interaction verification | 3 per feature |
+| E2E Test | Critical user journey verification | 1-2 per feature |
+
+## Behavior-First Principle
+
+### Observability Check (All YES = Include)
+
+| Check | Question | If NO |
+|-------|----------|-------|
+| Observable | Can user observe the result? | Exclude |
+| System Context | Does it require integration of multiple components? | Exclude |
+| Automatable | Can it run stably in CI environment? | Exclude |
+
+### Include/Exclude Criteria
+
+**Include**: Business logic accuracy, data integrity, user-visible features, error handling
+**Exclude**: External live connections, performance metrics, implementation details, UI layout
+
+## Skeleton Specification
+
+### Required Comment Format
+
+Each test skeleton MUST include:
+- **AC**: Original acceptance criteria text
+- **ROI**: Calculated score with Business Value and Frequency
+- **Behavior**: Trigger → Process → Observable Result format
+- **Metadata**: @category, @dependency, @complexity annotations
+
+## Implementation Rules
+
+### Behavior Verification
+
+| Step Type | Verification Target |
+|-----------|---------------------|
+| Trigger | Reproduce in test setup (Arrange) |
+| Process | Intermediate state or function call |
+| Observable Result | Final output value (return value, error message, log output) |
+
+**Pass Criteria**: Test passes if "observable result" is verified as return value or mock call argument
+
+### Integration Test Mock Boundaries
+
+| Judgment Criteria | Mock | Actual |
+|-------------------|------|--------|
+| Part of test target? | No → Can mock | Yes → Actual required |
+| External network communication? | Yes → Mock required | No → Actual recommended |
+
+### E2E Test Execution Conditions
+
+- Execute only after all components are implemented
+- Do not use mocks (full system integration required)
+
+## Review Criteria
+
+### Skeleton and Implementation Consistency
+
+| Check | Failure Condition |
+|-------|-------------------|
+| Behavior Verification | No assertion for "observable result" |
+| Verification Item Coverage | Listed verification items not included in assertions |
+| Mock Boundary | Internal components mocked in integration test |
+
+### Implementation Quality
+
+| Check | Failure Condition |
+|-------|-------------------|
+| AAA Structure | Arrange/Act/Assert separation unclear |
+| Independence | State sharing between tests, execution order dependency |
+| Reproducibility | Depends on date/random, results vary |
+| Readability | Test name and verification content don't match |

package/.agents/rules/core/metacognition.md

@@ -0,0 +1,153 @@
+# Metacognition Protocol
+
+## Purpose
+
+Self-assessment checkpoints.
+
+## When to Apply [MANDATORY CHECKPOINTS]
+
+**BLOCKING METACOGNITION REQUIRED at:**
+- [CHECKPOINT] Task type changes → CANNOT proceed without assessment
+- [CHECKPOINT] After completing ANY task from work plan → MUST evaluate before next task
+- [CHECKPOINT] When encountering error or unexpected result → ASSESS approach immediately
+- [CHECKPOINT] Before writing first line of new feature → VALIDATE approach first
+- [CHECKPOINT] When switching between major phases → CONFIRM all gates passed
+
+**ENFORCEMENT**: Skipping metacognition = CRITICAL VIOLATION
+
+## Assessment Questions
+
+### 1. Task Understanding
+
+- What is the fundamental goal?
+- Am I solving the root cause or symptom?
+- Do I have all necessary information?
+- Are success criteria clear and measurable?
+- What are the known unknowns at this point?
+
+### 2. Current State
+
+- What rules are currently loaded?
+- Which rules are actually being used?
+- What assumptions am I making?
+- What could go wrong?
+
+### 3. Approach Validation
+
+- Is my approach the simplest solution?
+- Am I following established patterns?
+- Have I considered alternatives?
+- Is this maintainable long-term?
+- What would make me reverse this decision? (Kill criteria)
+
+## Rule Selection Guide
+
+### By Task Type
+
+| Task Type | Essential Rules | Optional Rules |
+|-----------|----------------|----------------|
+| **Implementation** | language/rules.md, ai-development-guide.md | architecture patterns |
+| **Bug Fix** | ai-development-guide.md | debugging patterns |
+| **Design** | documentation-criteria.md | architecture patterns |
+| **Testing** | language/testing.md | coverage strategies |
+| **Refactoring** | ai-development-guide.md | design patterns |
+
+### Loading Strategy
+
+**Immediate needs**: Load only what's required now
+**Progressive loading**: Add rules as specific needs arise
+**Cleanup**: Unload rules after task completion
+
+Note: Context management is user's responsibility. Ask for guidance if unsure.
+
+## Common Decision Points
+
+### When Starting Work [BLOCKING CHECKLIST]
+☐ [MUST VERIFY] Task type and scale documented with evidence
+☐ [MUST VERIFY] Required rules LOADED and file paths listed
+☐ [MUST VERIFY] Success criteria MEASURABLE and specific
+☐ [MUST VERIFY] Approach validated against existing patterns
+
+**GATE: CANNOT start coding if ANY unchecked**
+
+### During Execution [PROGRESS GATES]
+☐ [VERIFY] Following work plan from `docs/design/work-plan.md`
+☐ [VERIFY] Making measurable progress (list completed items)
+☐ [EVALUATE] Additional rules needed? (load IMMEDIATELY if yes)
+☐ [EVALUATE] Blocked for >10 minutes? (MUST ask for help)
+
+**Dynamic Rule Loading Triggers:**
+- Same error occurs 2+ times → Load `ai-development-guide.md` for debugging patterns
+- "Performance" mentioned in requirements → Load optimization rules if available
+- "Security" mentioned in requirements → Load security guidelines if available
+- External API/service integration needed → Load integration patterns if available
+
+**ENFORCEMENT: If progress stalled → MANDATORY metacognition**
+
+### After Completion [EXIT GATES]
+☐ [VERIFIED] ALL completion criteria met with evidence
+☐ [VERIFIED] Code quality metrics passed (lint, test, build)
+☐ [VERIFIED] Documentation updated (if applicable)
+☐ [RECORDED] What worked/failed for next iteration
+
+**GATE: CANNOT mark complete without ALL verified**
+
+## Anti-Pattern Recognition
+
+| Pattern | Signs | Correction |
+|---------|-------|------------|
+| **Over-engineering** | Complex solution for simple problem | Simplify approach |
+| **Under-planning** | Jumping into code too quickly | Step back, plan first |
+| **Tunnel vision** | Ignoring alternatives | Consider other approaches |
+| **Quality debt** | Skipping tests or docs | Complete properly |
+| **Context bloat** | Loading unnecessary rules | Load only essentials |
+
+## Error Recovery
+
+When stuck:
+1. Identify what's blocking progress
+2. Check if it's a knowledge gap or logic error
+3. Review loaded rules for guidance
+4. Consider simpler approach
+5. Ask user for clarification
+
+**ERROR HANDLING PROTOCOL:**
+
+When encountering an error or blocker:
+- [IMMEDIATE] Execute metacognition assessment
+- [SEARCH] Look for similar patterns in codebase
+- [RE-READ] Relevant rule files for guidance
+- [EVALUATE] Can I solve this with available information?
+
+If unable to resolve:
+- [DOCUMENT] Exact error message and context
+- [EXPLAIN] What was attempted and why it failed
+- [REQUEST] User guidance with specific questions
+
+**PRINCIPLE: Ask for help when genuinely stuck, not after arbitrary attempt count**
+
+## Learning from Experience
+
+Track:
+- What worked well
+- What caused delays
+- Which rules were helpful
+- What patterns emerged
+- What to do differently
+
+## Guidelines
+
+- **Be honest**: Acknowledge when uncertain
+- **Be systematic**: Follow structured approach
+- **Be efficient**: Don't overthink simple tasks
+- **Be thorough**: Don't skip important steps
+- **Be adaptive**: Adjust approach based on feedback
+
+## Notes
+
+Remember:
+- Metacognition prevents costly mistakes
+- Regular reflection improves quality
+- It's okay to pause and think
+- Ask for help when genuinely stuck
+- Perfect is the enemy of good