agentic-code 0.5.1

package/.agents/tasks/technical-design.md

@@ -0,0 +1,432 @@
+# Technical Design
+
+## Required Rules [MANDATORY - MUST BE ACTIVE]
+
+**RULE AVAILABILITY VERIFICATION:**
+1. [VERIFY ACTIVE] `.agents/rules/core/metacognition.md` (loaded at session start)
+2. [LOAD IF NOT ACTIVE] `.agents/rules/core/documentation-criteria.md`
+3. [CONDITIONAL LOAD] `.agents/rules/contextual/architecture/implementation-approach.md` (if Medium scale 3+ files OR Large scale)
+
+**LOADING PROTOCOL:**
+- STEP 1: VERIFY metacognition.md is active from initial session setup
+- STEP 2: CHECK if documentation-criteria.md is active in working memory
+- STEP 3: If documentation-criteria.md NOT active → Execute BLOCKING READ
+- STEP 4: EVALUATE conditions for implementation-approach.md (Medium/Large scale: 3+ files)
+- STEP 5: If conditions met AND implementation-approach.md NOT active → Execute BLOCKING READ
+- STEP 6: CONFIRM all required rules active before proceeding
+
+## Plan Injection Requirement [MANDATORY]
+
+**Upon reading this file, IMMEDIATELY inject to work plan:**
+1. All BLOCKING READs identified in Loading Protocol above:
+   - `.agents/rules/core/documentation-criteria.md` (if not active)
+   - `.agents/rules/contextual/architecture/implementation-approach.md` (if conditions met)
+2. Mark each with "[From technical-design.md]" source tag
+3. Show evidence of injection:
+   ```
+   [PLAN INJECTION FROM technical-design.md]
+   Injected to work plan:
+   ✓ BLOCKING READ: documentation-criteria.md - ADR/Design Doc criteria
+   ✓ BLOCKING READ: implementation-approach.md - strategy selection (if applicable)
+   Status: VERIFIED
+   ```
+
+**ENFORCEMENT:** Cannot proceed without Plan Injection evidence
+
+**EVIDENCE REQUIRED:**
+```
+Rule Status Verification:
+✓ metacognition.md - ACTIVE
+✓ documentation-criteria.md - ACTIVE
+✓ implementation-approach.md - [ACTIVE/NOT NEEDED]
+```
+
+## Phase Entry Gate [BLOCKING - SYSTEM HALT IF VIOLATED]
+
+**CHECKPOINT: System CANNOT proceed until ALL boxes checked:**
+☐ [VERIFIED] Plan Injection completed (from task-analysis.md Step 8)
+☐ [VERIFIED] Work plan contains "BLOCKING READ technical-design.md" item
+☐ [VERIFIED] Project structure confirmed
+☐ [VERIFIED] PRD reviewed (if exists) with requirements understood
+☐ [VERIFIED] Related design documents investigation COMPLETED with evidence
+☐ [VERIFIED] Existing ADRs reviewed for relevant decisions
+☐ [VERIFIED] Existing codebase investigation COMPLETED with evidence
+☐ [VERIFIED] Similar functionality search EXECUTED with results documented
+☐ [VERIFIED] Required rules LOADED with file paths listed above
+☐ [VERIFIED] SESSION_BASELINE_DATE established and active
+
+**METACOGNITION GATE [MANDATORY]:**
+BEFORE starting design, execute metacognition assessment:
+- Understand fundamental goal (not surface task)
+- Verify all necessary information available
+- Confirm approach aligns with existing patterns
+
+**GATE ENFORCEMENT:**
+IF any box unchecked → HALT → Return to uncompleted step
+IF attempting to skip → CRITICAL ERROR
+
+## Purpose
+
+Create ADR and Design Documents.
+
+### ADR Creation Triggers [EVALUATE DURING DESIGN]:
+- Data flow changes → ADR-ARCH-DATA-FLOW
+- Architecture changes → ADR-ARCH-[SPECIFIC]
+- External dependency changes → ADR-DEPS-[NAME]
+- New technology introduction → ADR-TECH-[NAME] [BLOCKING: MUST CREATE]
+- Performance optimization → ADR-PERF-[ASPECT]
+- Security implementation → ADR-SEC-[FEATURE]
+
+**EVALUATION**: Check conditions above - if ANY trigger met, ADR creation is MANDATORY
+
+## Completion Conditions
+
+### For ADR:
+□ Problem background clearly stated
+□ Minimum 3 options evaluated
+□ Trade-offs explicitly documented
+□ Decision rationale recorded
+□ Latest technology research conducted
+□ References cited with URLs
+□ Consistency with existing architecture verified
+
+### For Design Doc:
+□ Agreement checklist completed
+□ Existing codebase analysis included
+□ Architecture approach documented
+□ Component structure defined
+□ Data flow mapped
+□ Integration points identified
+□ Error handling strategy defined
+□ Testing strategy outlined
+□ Acceptance criteria defined and verifiable
+□ References cited
+
+## Mandatory Process Before Document Creation [STRICT COMPLIANCE]
+
+**These steps MUST be completed to pass the entry gate:**
+
+### 1. Existing Documentation Investigation [REQUIRED - CANNOT SKIP]
+Must be performed before any design:
+
+1. **PRD Investigation** (if applicable)
+   - Check for related PRD in `docs/prd/` directory
+   - Review requirements and success criteria
+   - Note any constraints or scope boundaries defined
+   - Include PRD reference in design doc header
+
+2. **Related Design Documents Search**
+   - Search existing designs in `docs/design/` directory
+   - Identify similar or dependent features
+   - Review architectural patterns used
+   - Note integration points and data flows
+
+3. **Existing ADRs Review**
+   - Search ADRs in `docs/adr/` directory
+   - Identify relevant technical decisions
+   - Check for superseded ADRs that might need updating
+   - List applicable ADRs in "Prerequisite ADRs" section
+
+### 2. Existing Code Investigation [REQUIRED - CANNOT SKIP]
+Must be performed after documentation review:
+
+1. **Implementation File Path Verification**
+   - First grasp overall project structure
+   - Then identify target files by searching for relevant component/module names
+   - Record and distinguish between existing implementation locations and planned new locations
+
+2. **Existing API Investigation** (Only when changing existing features)
+   - List major public operations of target component
+   - Identify call sites by searching for component usage patterns
+
+3. **Similar Functionality Search** (Pattern 5 prevention from ai-development-guide.md)
+   - Search existing code for keywords related to planned functionality
+   - Look for implementations with same domain, responsibilities, or configuration patterns
+   - Decision and action:
+     - Similar functionality found → Use that implementation (do not create new)
+     - Similar functionality is technical debt → Create ADR improvement proposal
+     - No similar functionality → Proceed with new implementation
+
+4. **Include in Design Doc**
+   - Always include investigation results in "## Existing Codebase Analysis" section
+   - Clearly document similar functionality search results
+   - Record adopted decision and rationale
+
+### 3. Agreement Checklist【MOST IMPORTANT】
+Must be performed at the beginning of Design Doc creation:
+
+1. **List agreements with user in bullet points**
+   - Scope (what to change)
+   - Non-scope (what not to change)
+   - Constraints (compatibility requirements, etc.)
+   - Performance requirements
+
+2. **Confirm reflection in design**
+   - [ ] Specify where each agreement is reflected
+   - [ ] Confirm no design contradicts agreements
+   - [ ] If any agreements not reflected, state reason
+
+### 4. Latest Information Research [BLOCKING REQUIREMENT]
+
+**Web research MUST use SESSION_BASELINE_DATE year - NEVER hardcoded years:**
+- Format: "[technology] best practices [YEAR from SESSION_BASELINE_DATE]"
+- Required for: New technology/library introduction, security implementations
+- Verify: Latest versions, breaking changes, security updates as of SESSION_BASELINE_DATE
+
+**Search Examples**: `[tech] best practices [YEAR]`, `[framework] official docs`
+
+## ADR Creation Guidelines
+
+### ADR Superseding Process [MANDATORY FOR RELATED ADRS]
+
+When creating an ADR that replaces or modifies a previous decision:
+
+1. **Identify Related ADRs**
+   - Search for ADRs covering the same domain/technology
+   - Check for ADRs that would be contradicted by new decision
+   - List all ADRs that need to be superseded
+
+2. **Update Existing ADR Status**
+   - Change status of old ADR: `Status: Superseded by ADR-XXXX`
+   - Add superseding note with date and new ADR reference
+   - DO NOT delete old ADRs - maintain history
+
+3. **Reference in New ADR**
+   - Add "Supersedes: ADR-YYYY" in header
+   - Explain what changed and why
+   - Maintain traceability of decision evolution
+
+### ADR Structure
+
+```markdown
+# ADR-XXXX: [Title]
+Status: Proposed
+Supersedes: ADR-YYYY (if applicable)
+
+## Background
+[Technical challenges and constraints in 1-2 sentences]
+
+## Options
+
+### Option A: [Approach Name]
+- Overview: [One sentence]
+- Benefits: [2-3 items]
+- Drawbacks: [2-3 items]
+- Effort: X days
+- Risk: Low/Medium/High
+
+### Option B/C: [Similarly structured, minimum 3 options total]
+
+## Comparison Matrix
+| Evaluation Axis | Option A | Option B | Option C |
+|----------------|----------|----------|----------|
+| Implementation Effort | X days | Y days | Z days |
+| Maintainability | High/Med/Low | ... | ... |
+| Performance Impact | +/-/None | ... | ... |
+
+## Decision
+Option [X] selected. Rationale: [2-3 sentences with trade-offs]
+
+### Decision Details
+
+| Item | Content |
+|------|---------|
+| **Decision** | [The decision in one sentence] |
+| **Why now** | [Why this needs to happen now (timing rationale)] |
+| **Why this** | [Why this option over alternatives (1-3 lines)] |
+| **Known unknowns** | [At least one uncertainty at this point] |
+| **Kill criteria** | [One signal that should trigger reversal of this decision] |
+
+## Implementation Guidelines
+[Principle-based guidelines]
+
+## References
+- [Documentation](URL) - Description
+```
+
+## Design Doc Creation Guidelines
+
+### Design Doc Structure
+
+````markdown
+# Technical Design: [Feature Name]
+
+## PRD Reference
+- PRD: `docs/prd/[feature-name]-prd.md` (if applicable)
+- Requirements addressed: [key requirements]
+
+## Overview
+[Brief description]
+
+## Design Summary (Meta)
+
+```yaml
+design_type: "new_feature|extension|refactoring"
+risk_level: "low|medium|high"
+main_constraints:
+  - "[constraint 1]"
+  - "[constraint 2]"
+biggest_risks:
+  - "[risk 1]"
+  - "[risk 2]"
+unknowns:
+  - "[uncertainty 1]"
+  - "[uncertainty 2]"
+```
+
+## Agreement Checklist
+- [ ] Scope: [what to implement]
+- [ ] Non-scope: [what not to change]
+- [ ] Constraints: [limitations]
+- [ ] Performance: [requirements]
+
+## Existing Codebase Analysis
+[Investigation results, similar functionality, decision]
+
+## Requirements
+[Functional, Non-functional, Constraints]
+
+## Acceptance Criteria
+### Functional Requirements
+- [ ] [Specific testable conditions]
+
+### Non-functional Requirements
+- [ ] [Performance/Security metrics]
+
+## Architecture
+
+### Approach
+[Selected pattern and rationale]
+
+### Components
+[Component list with responsibilities]
+
+### Data Flow
+[System data movement]
+
+### Integration Points
+[External systems, APIs, Databases]
+
+### Integration Point Analysis [MANDATORY for feature modifications]
+[Use format from section above]
+
+## Implementation Details
+
+### Technology Stack
+[Languages, frameworks, libraries, tools]
+
+### Change Impact Map
+[Target, Direct impact, Indirect impact]
+
+## Testing Strategy
+[Unit and integration test approaches]
+
+## Risks and Mitigations
+[Technical risks]
+
+## References
+- [Source](URL) - Description
+````
+
+## Acceptance Criteria Creation Guidelines
+
+**Principle**: Specific, verifiable conditions that translate to test cases
+**Good**: "After auth with correct credentials, navigates to dashboard"
+**Bad**: "Login works"
+
+### EARS Format [RECOMMENDED]
+
+Use EARS keywords to standardize AC structure:
+
+| Keyword | Test Type | Example |
+|---------|-----------|---------|
+| **When** | Event trigger | "**When** user clicks submit, the system shall save the form" |
+| **While** | State-based | "**While** logged in, the system shall display username" |
+| **If-then** | Conditional | "**If** cart is empty, **then** show empty message" |
+| (none) | Always-true | "The system shall encrypt all passwords" |
+
+### Behavior-First Principle [CRITICAL]
+
+**Core Principle**: AC = User-observable behavior verifiable in isolated CI environment
+
+**BEFORE writing any AC, apply 3 mandatory checks:**
+
+#### 1. User-Observable Check
+**Question**: "Can a user (or system operator) observe this behavior?"
+- **If NO** → This is an **implementation detail**, exclude from AC
+- **If YES** → Continue to check 2
+
+**Examples**:
+- ❌ Bad (Implementation Detail): "Password must be hashed using bcrypt with 10 salt rounds"
+- ✅ Good (User-Observable): "After failed login attempts, user is locked out for 15 minutes"
+
+#### 2. Verification Context Check
+**Question**: "Can this be verified without full system integration?"
+- **If YES** → This is **unit/component level**, exclude from integration/E2E AC
+- **If NO** → This is a valid AC for integration/E2E tests, continue to check 3
+
+**Examples**:
+- ❌ Bad (Unit-level): "calculateTax function returns correct value for given input"
+- ✅ Good (Integration-level): "After checkout, order total includes correct tax amount"
+
+#### 3. CI Environment Check
+**Question**: "Is this verifiable deterministically in CI?"
+- **If NO** → Exclude (e.g., performance metrics, real external services)
+- **If YES** → Valid AC
+
+**Examples**:
+- ❌ Bad (Non-deterministic): "API response time must be < 200ms"
+- ✅ Good (Deterministic): "System processes checkout requests without blocking user interaction"
+
+**Enhanced Include/Exclude Criteria**:
+
+**Include (High Automation ROI)**:
+- Business logic correctness (calculations, state transitions)
+- Data integrity and persistence behavior
+- User-visible functionality completeness
+- Error handling behavior (what user sees/experiences)
+
+**Exclude (Low Automation ROI)**:
+- External service real connections → Use contract/interface verification instead
+- Performance metrics → Non-deterministic in CI, use dedicated performance testing
+- Implementation details (hashing algorithms, internal function calls) → Focus on observable behavior
+- UI layout specifics → Focus on information availability, not pixel-perfect rendering
+
+## Design Validation
+
+Verify: Completeness, Consistency, Feasibility, Testability, Maintainability, Scalability
+
+## Deliverables
+
+### When ADR needed:
+- ADR document in `docs/adr/ADR-[4-digit]-[title].md`
+- Status: "Proposed" → "Accepted" or "Rejected" after decision
+
+### Always:
+- Design document in `docs/design/[feature-name]-design.md`
+- Include all investigation results
+- Include all references
+
+## Post-Design Metacognition Gate [MANDATORY]
+
+**AFTER completing design document:**
+☐ Execute "After Completion" metacognition checklist
+☐ Verify design addresses all requirements
+☐ Confirm technical approach is simplest viable solution
+☐ Document any assumptions or risks identified
+☐ Evaluate if additional research needed
+
+**CANNOT proceed to implementation without:**
+- Metacognition assessment complete
+- Design document created
+- User approval received
+
+## Anti-Patterns to Avoid
+
+**ADR Anti-Patterns**
+Recommended: Evaluate 3+ options with research-backed trade-offs
+Reason: Single option decisions lack validation; options without drawbacks are unrealistic
+
+**Design Anti-Patterns**
+Recommended: Specific, testable acceptance criteria with impact analysis
+Reason: Vague criteria prevent verification; missing impact analysis causes integration issues

package/.agents/tasks/technical-document-review.md

@@ -0,0 +1,254 @@
+# Document Review
+
+## Required Rules [MANDATORY - MUST BE ACTIVE]
+
+**RULE AVAILABILITY VERIFICATION:**
+1. [LOAD IF NOT ACTIVE] `.agents/rules/core/documentation-criteria.md`
+2. [CONDITIONAL LOAD] `.agents/rules/core/testing-strategy.md` (if reviewing Design Doc with test strategy)
+
+**LOADING PROTOCOL:**
+- STEP 1: CHECK if documentation-criteria.md is active in working memory
+- STEP 2: If documentation-criteria.md NOT active → Execute BLOCKING READ
+- STEP 3: EVALUATE if testing-strategy.md needed (Design Doc with test strategy section)
+- STEP 4: If needed AND NOT active → Execute BLOCKING READ
+- STEP 5: CONFIRM all required rules active before proceeding
+
+## Purpose
+
+Review technical documents (Design Docs, ADRs, PRDs) for completeness, consistency, and quality. Identify gaps, validate structure compliance, and evaluate failure scenario coverage.
+
+## When to Use
+
+- When reviewing existing design documents
+- Before approving technical decisions
+- When evaluating document quality from third-party perspective
+
+## Required Information
+
+- **documentPath**: Path to document to review (required)
+- **documentType**: Type of document (required)
+  - `design-doc`: Technical Design Document
+  - `adr`: Architecture Decision Record
+  - `prd`: Product Requirements Document
+- **templatePath**: Path to template for validation baseline (optional - uses default if not provided)
+- **reviewMode**:
+  - `full`: Complete validation (default)
+  - `structure`: Structure compliance only
+  - `content`: Content quality only
+  - `failure-scenarios`: Failure scenario coverage only
+
+## Completion Conditions
+
+□ Document loaded and type confirmed
+□ Structure compliance verified against template
+□ Content quality evaluated
+□ Failure scenarios reviewed (for Design Docs)
+□ Issues documented with severity
+□ Verdict determined with rationale
+
+## Review Process
+
+### Stage 1: Document Type Identification
+
+Confirm document type and determine validation baseline:
+- If template path provided → Use specified template as baseline
+- If no template provided → Request template path from user
+- Default templates by type:
+  - Design Doc → `.agents/tasks/technical-design.md`
+  - ADR → ADR section in `.agents/tasks/technical-design.md`
+  - PRD → PRD section in `.agents/rules/core/documentation-criteria.md`
+
+### Stage 2: Structure Compliance Check
+
+#### For Design Doc
+
+| Required Section | Check Item |
+|-----------------|------------|
+| Overview | Purpose clearly stated |
+| Design Summary (Meta) | risk_level, constraints, unknowns defined |
+| Agreement Checklist | Scope/Non-scope/Constraints documented |
+| Existing Codebase Analysis | Investigation results included |
+| Acceptance Criteria | Specific, testable conditions |
+| Architecture | Approach, components, data flow defined |
+| Integration Points | External dependencies identified |
+| Testing Strategy | Test approach outlined |
+| Risks and Mitigations | Technical risks documented |
+| References | Sources cited |
+
+#### For ADR
+
+| Required Section | Check Item |
+|-----------------|------------|
+| Background | Problem context in 1-2 sentences |
+| Options | Minimum 3 options evaluated |
+| Comparison Matrix | Trade-offs quantified |
+| Decision | Selected option with rationale |
+| Decision Details | Why now / Why this / Known unknowns / Kill criteria |
+| Implementation Guidelines | Principle-based guidelines |
+| References | Documentation URLs cited |
+
+#### For PRD
+
+| Required Section | Check Item |
+|-----------------|------------|
+| Business Requirements | User value articulated |
+| Success Metrics | KPIs in measurable format |
+| User Stories | Use cases documented |
+| MoSCoW Prioritization | Must/Should/Could/Won't defined |
+| Scope Boundaries | MVP and future phases separated |
+
+### Stage 3: Content Quality Check
+
+| Check Item | Verification Content | Failure Condition |
+|------------|---------------------|-------------------|
+| Specificity | Concrete, not vague | Abstract statements without examples |
+| Testability | Acceptance criteria verifiable | Cannot be tested |
+| Consistency | No internal contradictions | Sections contradict each other |
+| Completeness | All required sections present | Missing sections |
+| Clarity | Unambiguous language | Multiple interpretations possible |
+
+### Stage 4: Failure Scenario Review (Design Docs Only)
+
+Identify failure scenarios across three categories:
+
+| Category | Description | Required Coverage |
+|----------|-------------|-------------------|
+| Normal usage | Failures during typical operation | At least 1 scenario |
+| High load | Failures under stress | At least 1 scenario |
+| External failures | Failures from dependencies | At least 1 scenario |
+
+For each identified scenario, verify:
+- Failure scenario is explicitly documented
+- Bottleneck element is specified
+- Mitigation strategy is defined
+
+### Stage 5: Technical Claim Verification
+
+When sources exist:
+- Verify claims with current best practices
+- Check if referenced technologies/versions are current
+- Flag outdated information
+
+## Validation Checklist
+
+### Structure Validation
+- [ ] All required sections present
+- [ ] Section order follows template
+- [ ] Formatting consistent
+
+### Content Validation
+- [ ] Acceptance criteria specific and testable
+- [ ] Technical decisions justified
+- [ ] Risks identified and mitigated
+- [ ] References cited and valid
+
+### Failure Scenario Validation (Design Docs)
+- [ ] Normal usage failure scenario identified
+- [ ] High load failure scenario identified
+- [ ] External failure scenario identified
+- [ ] Bottlenecks specified for each scenario
+
+### Consistency Validation
+- [ ] No contradictions between sections
+- [ ] Terminology used consistently
+- [ ] Scope aligned throughout document
+
+## Output Format
+
+### Status Determination
+
+**approved**:
+- All required sections present and complete
+- Content is specific and testable
+- Failure scenarios covered (Design Docs)
+- No high severity issues
+
+**needs_revision**:
+- Some sections incomplete
+- Content quality issues exist
+- Failure scenarios partially covered
+- Medium severity issues present
+
+**blocked**:
+- Critical sections missing
+- Major contradictions found
+- Document type unclear
+- Cannot proceed without significant rewrite
+
+### Report Structure
+
+```
+[REVIEW RESULT]
+documentType: design-doc | adr | prd
+documentPath: [path]
+verdict: approved | needs_revision | blocked
+completenessRate: [X]%
+
+[STRUCTURE COMPLIANCE]
+requiredSections: [count]
+presentSections: [count]
+missingSections:
+  - [section name]
+
+[CONTENT QUALITY]
+issues:
+  - severity: high | medium | low
+    section: [section name]
+    issue: [problem description]
+    suggestion: [specific improvement]
+
+[FAILURE SCENARIO REVIEW] (Design Docs only)
+normalUsage:
+  covered: yes | no
+  scenario: [if covered]
+  bottleneck: [if covered]
+highLoad:
+  covered: yes | no
+  scenario: [if covered]
+  bottleneck: [if covered]
+externalFailures:
+  covered: yes | no
+  scenario: [if covered]
+  bottleneck: [if covered]
+
+[VERDICT]
+decision: approved | needs_revision | blocked
+reason: [decision rationale]
+prioritizedActions:
+  1. [highest priority fix]
+  2. [next fix]
+```
+
+## Review Principles
+
+1. **Template Compliance**
+   - Use document type template as baseline
+   - Verify all required elements present
+
+2. **Constructive Feedback**
+   - Provide specific improvement suggestions
+   - Prioritize issues by impact
+
+3. **Objectivity**
+   - Evaluate against documented standards
+   - Avoid subjective preferences
+
+4. **Actionability**
+   - Each issue should have clear resolution path
+   - Distinguish must-fix from nice-to-have
+
+## Escalation Criteria
+
+Recommend escalation when:
+- Document contradicts existing ADRs
+- Security implications not addressed
+- Scope significantly exceeds original requirements
+- Technical claims cannot be verified
+
+## Anti-Patterns to Avoid
+
+- Approving documents with missing required sections
+- Ignoring vague acceptance criteria
+- Overlooking failure scenario gaps
+- Accepting documents without references
+- Providing feedback without specific solutions