agentic-code 0.5.1

package/.agents/tasks/implementation.md

@@ -0,0 +1,199 @@
+# Implementation
+
+## Required Rules [MANDATORY - MUST BE ACTIVE]
+
+**RULE AVAILABILITY VERIFICATION:**
+1. [VERIFY ACTIVE] `.agents/rules/core/metacognition.md`
+2. [LOAD IF NOT ACTIVE] `.agents/rules/language/rules.md`
+3. [LOAD IF NOT ACTIVE] `.agents/rules/language/testing.md`
+
+**LOADING PROTOCOL:**
+- STEP 1: VERIFY metacognition.md is active from initial session setup
+- STEP 2: CHECK if language/rules.md is active in working memory
+- STEP 3: If language/rules.md NOT active → Execute BLOCKING READ
+- STEP 4: CHECK if testing.md is active in working memory
+- STEP 5: If testing.md NOT active → Execute BLOCKING READ
+- STEP 6: CONFIRM all rules active before writing ANY code
+
+## Plan Injection Requirement [MANDATORY]
+
+**Upon reading this file, IMMEDIATELY inject to work plan:**
+1. All BLOCKING READs identified in Loading Protocol above:
+   - `.agents/rules/language/rules.md` (if not active)
+   - `.agents/rules/language/testing.md` (if not active)
+2. Mark each with "[From implementation.md]" source tag
+3. Show evidence of injection:
+   ```
+   [PLAN INJECTION FROM implementation.md]
+   Injected to work plan:
+   ✓ BLOCKING READ: language/rules.md - development standards
+   ✓ BLOCKING READ: language/testing.md - TDD process
+   Status: VERIFIED
+   ```
+
+**ENFORCEMENT:** Cannot proceed without Plan Injection evidence
+
+**EVIDENCE REQUIRED:**
+```
+Rule Status Verification:
+✓ metacognition.md - ACTIVE (from session setup)
+✓ language/rules.md - ACTIVE (loaded/verified)
+✓ language/testing.md - ACTIVE (loaded/verified)
+```
+
+## Phase Entry Gate [BLOCKING - SYSTEM HALT IF VIOLATED]
+
+**CHECKPOINT: System CANNOT write ANY CODE until ALL boxes checked:**
+☐ [VERIFIED] THIS FILE (`implementation.md`) has been READ and is active
+☐ [VERIFIED] Plan Injection completed (from implementation.md Plan Injection Requirement)
+☐ [VERIFIED] All required rules listed above are LOADED and active
+☐ [VERIFIED] Work plan EXISTS with task definitions
+☐ [VERIFIED] Work plan contains ALL BLOCKING READs from this file
+☐ [VERIFIED] Current task identified from work plan
+☐ [VERIFIED] TDD process understood (Red-Green-Refactor-Verify)
+☐ [VERIFIED] SESSION_BASELINE_DATE established and active
+
+**METACOGNITION GATE [MANDATORY]:**
+BEFORE writing first line of code:
+- Understand what needs to be built
+- Verify approach follows existing patterns
+- Confirm TDD cycle will be followed
+
+**GATE ENFORCEMENT:**
+IF any box unchecked → HALT → Return to uncompleted step
+IF attempting to write code without gates → CRITICAL ERROR
+
+## Purpose
+
+Implement code using TDD process.
+
+## When to Use
+
+- Writing new code
+- Modifying existing code
+- Implementing features from design
+- Fixing bugs
+- Refactoring
+
+## Task Exit: Confirm all complete
+
+- Tests written and passing?
+- Code implements requirements?
+- Quality checks executed with 0 errors?
+- Changes committed to git?
+- Work plan task checkbox marked [x]?
+
+## TDD Implementation Process
+
+### Every code change follows:
+
+**1. RED Phase - Write failing test first**
+   - Define expected behavior in test
+   - Run test to confirm it fails
+   - No implementation code yet
+
+**2. GREEN Phase - Make test pass**
+   - Write minimal code to pass test
+   - Focus only on making test green
+   - Run test to confirm it passes
+
+**3. REFACTOR Phase - Improve code**
+   - Clean up implementation
+   - Apply coding standards from language/rules.md
+   - Ensure test still passes
+
+**4. VERIFY Phase - Quality checks**
+   - Execute ALL commands from language/testing.md Quality Check Commands section
+   - Confirm ALL checks pass with 0 errors
+   - Ready for commit
+
+**5. COMMIT Phase - Version control [MANDATORY]**
+   - Stage changes for current implementation
+   - Create commit with descriptive message
+   - Commit message format: "feat: [what was implemented]" or follow work plan task name if available
+   - ENFORCEMENT: Implementation task NOT complete until committed
+   - NOTE: Skip if user explicitly says "don't commit"
+
+## Internal Progress Tracking
+
+Track these phases internally:
+```
+Current Task: [task name]
+□ RED Phase: Test written
+□ GREEN Phase: Test passing
+□ REFACTOR Phase: Code cleaned
+□ VERIFY Phase: Quality checks passed (0 errors)
+□ COMMIT Phase: Changes committed
+```
+
+## Common Patterns with TDD
+
+**New Feature**
+1. Write test for new behavior (RED)
+2. Implement minimal solution (GREEN)
+3. Refactor and add edge cases (REFACTOR)
+4. Verify quality (VERIFY)
+
+**Bug Fix**
+1. Write test that reproduces bug (RED)
+2. Fix the bug (GREEN)
+3. Ensure no regression (REFACTOR)
+4. Verify quality (VERIFY)
+
+**Refactoring**
+1. Ensure tests exist and pass
+2. Make small changes
+3. Run tests after each change
+4. Maintain behavior
+
+### 5. Language-Agnostic Standards
+
+Regardless of language:
+- Clear variable names
+- Consistent formatting
+- Proper indentation
+- Logical file organization
+- Separation of concerns
+
+### 6. Testing Approach
+
+**REFERENCE `.agents/rules/language/testing.md` for complete testing strategy including:**
+- Test types and granularity
+- Test-first development process
+- Coverage requirements
+- Mock and stub usage patterns
+
+### 7. Security Considerations
+
+Always:
+- Validate all inputs
+- Sanitize user data
+- Use parameterized queries
+- Avoid hardcoded secrets
+- Follow principle of least privilege
+
+## Anti-Patterns to Avoid
+
+1. **God functions**: Doing too much in one function
+2. **Magic numbers**: Use named constants
+3. **Deep nesting**: Max 3 levels of indentation
+4. **Ignoring errors**: Always handle or propagate
+5. **Premature optimization**: Make it work, then optimize
+6. **Copy-paste coding**: Extract common code
+7. **Unclear naming**: Be explicit, not clever
+
+## Final Quality Gate
+
+**REFERENCE `.agents/tasks/quality-assurance.md` for complete quality checklist**
+
+Essential completion requirements:
+□ ALL quality standards from quality-assurance.md satisfied
+□ ALL language requirements from language/rules.md met
+□ ALL testing requirements from testing.md completed
+□ Work plan task checkbox updated to [✓]
+□ Metacognition "After Completion" executed
+
+**FINAL METACOGNITION GATE [BLOCKING]:**
+- Cannot mark task complete without metacognition assessment
+- Must document what worked/failed for future reference
+- Must evaluate if additional rules needed for next task

package/.agents/tasks/integration-test-review.md

@@ -0,0 +1,132 @@
+# Integration Test Review
+
+## Required Rules [MANDATORY - MUST BE ACTIVE]
+
+**RULE AVAILABILITY VERIFICATION:**
+1. [LOAD IF NOT ACTIVE] `.agents/rules/language/testing.md`
+2. [LOAD IF NOT ACTIVE] `.agents/rules/core/integration-e2e-testing.md`
+
+**LOADING PROTOCOL:**
+- STEP 1: CHECK if language/testing.md is active in working memory
+- STEP 2: If language/testing.md NOT active → Execute BLOCKING READ
+- STEP 3: CHECK if integration-e2e-testing.md is active in working memory
+- STEP 4: If integration-e2e-testing.md NOT active → Execute BLOCKING READ
+- STEP 5: CONFIRM all required rules active before proceeding
+
+## Purpose
+
+Verify implementation quality of integration and E2E tests. Evaluate consistency between skeleton comments (AC, Behavior, metadata) and actual test implementation.
+
+## When to Use
+
+- After integration/E2E test implementation is complete
+- Before Quality Assurance phase
+- When test skeletons have been converted to actual test implementations
+
+## Required Information
+
+- **testFile**: Path to the test file to review (required)
+- **designDocPath**: Path to related Design Doc (optional)
+
+## Completion Conditions
+
+□ All skeleton comments verified against implementation
+□ Behavior verification assertions present for all observable results
+□ AAA structure confirmed in all test cases
+□ Mock boundaries appropriate (external=mock, internal=actual)
+□ Test independence verified (no shared mutable state)
+□ Quality issues identified and documented
+
+## Review Process
+
+### Stage 1: Skeleton Comment Extraction
+
+Extract the following from the test file:
+- `AC:` - Acceptance criteria reference
+- `ROI:` - ROI score and values
+- `Behavior:` - Trigger → Process → Observable Result
+- `@category:` - Test category
+- `@dependency:` - Component dependencies
+- `@complexity:` - Complexity level
+
+### Stage 2: Skeleton and Implementation Consistency Check
+
+For each test case, verify:
+
+| Check Item | Verification Content | Failure Condition |
+|------------|---------------------|-------------------|
+| AC Correspondence | Test implemented for AC comment | Pending/todo marker remains |
+| Behavior Verification | Assertion exists for "observable result" | No assertion |
+| Verification Item Coverage | All listed items included in assertions | Item missing |
+
+### Stage 3: Implementation Quality Check
+
+| Check Item | Verification Content | Failure Condition |
+|------------|---------------------|-------------------|
+| AAA Structure | Arrange/Act/Assert separation clear | Separation unclear |
+| Independence | No state sharing between tests | Shared state modified |
+| Reproducibility | No direct use of current time or random values | Non-deterministic elements |
+| Readability | Test name matches verification content | Name and content diverge |
+
+### Stage 4: Mock Boundary Check (Integration Tests Only)
+
+| Judgment Criteria | Expected State | Failure Condition |
+|-------------------|----------------|-------------------|
+| External API | Mock required | Actual HTTP communication |
+| Internal Components | Use actual | Unnecessary mocking |
+
+## Output Format
+
+### Status Determination
+
+**approved**:
+- All ACs have implemented tests (no pending/todo markers)
+- All observable results have assertions
+- No quality issues or only low priority ones
+
+**needs_revision**:
+- Pending/todo markers remain
+- Behavior verification missing
+- Medium to high priority quality issues exist
+
+**blocked**:
+- Skeleton file not found
+- AC intent unclear
+- Major contradiction between Design Doc and implementation
+
+### Report Structure
+
+```
+[REVIEW RESULT]
+status: approved | needs_revision | blocked
+testFile: [path]
+summary: [result summary]
+
+[SKELETON COMPLIANCE]
+totalACs: [count]
+implementedACs: [count]
+pendingTodos: [count]
+missingAssertions: [list if any]
+
+[QUALITY ISSUES]
+- severity: high | medium | low
+  category: [aaa_structure | independence | reproducibility | mock_boundary | readability]
+  location: [file:line]
+  description: [problem description]
+  suggestion: [fix proposal]
+
+[VERDICT]
+decision: approved | needs_revision | blocked
+reason: [decision reason]
+prioritizedActions:
+  1. [highest priority fix]
+  2. [next fix]
+```
+
+## Anti-Patterns to Avoid
+
+- Approving tests with remaining pending/todo markers
+- Ignoring missing assertions for observable results
+- Overlooking shared mutable state between tests
+- Accepting excessive mocking of internal components
+- Skipping AAA structure verification

package/.agents/tasks/prd-creation.md

@@ -0,0 +1,336 @@
+# Product Requirements Document (PRD) Creation
+
+## 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`
+
+**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: CONFIRM all 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)
+2. Mark each with "[From prd-creation.md]" source tag
+3. Show evidence of injection:
+   ```
+   [PLAN INJECTION FROM prd-creation.md]
+   Injected to work plan:
+   ✓ BLOCKING READ: documentation-criteria.md - PRD creation criteria
+   Status: VERIFIED
+   ```
+
+**ENFORCEMENT:** Cannot proceed without Plan Injection evidence
+
+**EVIDENCE REQUIRED:**
+```
+Rule Status Verification:
+✓ metacognition.md - ACTIVE (from session setup)
+✓ documentation-criteria.md - ACTIVE (loaded/verified)
+```
+
+## Phase Entry Gate [BLOCKING - SYSTEM HALT IF VIOLATED]
+
+**CHECKPOINT: System CANNOT proceed until ALL boxes checked:**
+☐ [VERIFIED] THIS FILE (`prd-creation.md`) has been READ and is active
+☐ [VERIFIED] Plan Injection completed (from prd-creation.md Plan Injection Requirement)
+☐ [VERIFIED] Work plan contains ALL BLOCKING READs from this file
+☐ [VERIFIED] Project structure confirmed
+☐ [VERIFIED] Existing PRDs investigation COMPLETED with evidence
+☐ [VERIFIED] Related documentation search EXECUTED with results documented
+☐ [VERIFIED] Required rules LOADED with file paths listed above
+☐ [VERIFIED] User requirements gathered and clarified
+☐ [VERIFIED] SESSION_BASELINE_DATE established and active
+
+**METACOGNITION GATE [MANDATORY]:**
+BEFORE starting PRD creation, execute metacognition assessment:
+- Understand business goals (not just technical implementation)
+- Verify all stakeholder needs identified
+- Confirm user value is clearly defined
+
+**GATE ENFORCEMENT:**
+IF any box unchecked → HALT → Return to uncompleted step
+IF attempting to skip → CRITICAL ERROR
+
+## Purpose
+
+Create Product Requirements Documents for new features or significant changes.
+
+## When to Use
+
+### PRD Required When [AUTOMATIC TRIGGER]:
+- New feature addition
+- Major user experience changes
+- Business logic fundamental changes
+- Multiple stakeholder impact
+- New product/service launch
+- Significant workflow modifications
+
+**ENFORCEMENT**: Starting implementation without PRD for these conditions = REQUIREMENTS PHASE FAILURE
+
+### PRD Not Required When:
+- Simple bug fixes
+- Internal refactoring (no user impact)
+- Documentation updates only
+- Minor UI tweaks
+- Performance optimization (no behavior change)
+
+## Completion Conditions
+
+### For PRD:
+□ Business requirements clearly stated
+□ User personas identified
+□ User stories with acceptance criteria defined
+□ Success metrics (KPIs) quantified
+□ Scope explicitly defined (what's included/excluded)
+□ MoSCoW prioritization completed (Must/Should/Could/Won't)
+□ MVP vs Future phases separated
+□ Risks and assumptions documented
+□ Timeline/milestones outlined
+□ User journey diagram created
+□ Scope boundary diagram included
+
+## Mandatory Process Before Document Creation [STRICT COMPLIANCE]
+
+**These steps MUST be completed to pass the entry gate:**
+
+### 1. Existing Documentation Investigation [REQUIRED - CANNOT SKIP]
+
+1. **Existing PRDs Search**
+   - Search for PRDs in `docs/prd/` directory
+   - Review related feature PRDs for context and dependencies
+   - Identify potential conflicts or overlaps
+
+2. **Related Design Docs Investigation**
+   - Search design docs in `docs/design/` directory
+   - Understand existing technical decisions that might constrain requirements
+   - Note integration points with existing features
+
+3. **Current System Analysis** (For feature updates)
+   - Identify current functionality and pain points
+   - Document what users currently do vs what they want to do
+   - Gather metrics on current usage if available
+
+4. **Include in PRD**
+   - Always include investigation results in "## Context & Background" section
+   - Reference related PRDs and their relationships
+   - Document assumptions based on existing system
+
+### 2. Requirements Gathering Checklist [MOST IMPORTANT]
+
+1. **User Requirements**
+   - [ ] Target users identified (personas)
+   - [ ] User problems/needs documented
+   - [ ] Desired outcomes specified
+   - [ ] Success criteria from user perspective
+
+2. **Business Requirements**
+   - [ ] Business goals aligned
+   - [ ] ROI or value proposition defined
+   - [ ] Compliance/regulatory requirements checked
+   - [ ] Budget constraints acknowledged
+
+3. **Technical Constraints** (high-level only)
+   - [ ] Platform limitations identified
+   - [ ] Integration requirements noted
+   - [ ] Performance expectations set
+   - [ ] Security requirements listed
+
+### 3. Stakeholder Research [BLOCKING REQUIREMENT]
+
+**Information Gathering:**
+- Interview questions for stakeholders
+- Competitive analysis (if applicable)
+- Market research findings
+- User feedback/requests analysis
+
+**Required Research Areas:**
+- Similar features in competing products
+- Industry best practices
+- User behavior patterns
+- Regulatory requirements
+
+## PRD Creation Guidelines
+
+### PRD Structure
+
+```markdown
+# PRD: [Feature Name]
+
+## Executive Summary
+[1-2 paragraphs summarizing the feature and its value]
+
+## Context & Background
+- Current situation
+- Problem statement
+- Opportunity identified
+- References to related PRDs
+
+## User Personas
+### Primary Users
+- [Persona name]: [Description, needs, goals]
+
+### Secondary Users
+- [Persona name]: [Description, needs, goals]
+
+## User Stories
+### Epic: [High-level feature]
+- **As a** [user type]
+- **I want to** [action]
+- **So that** [benefit]
+
+#### Story 1: [Specific functionality]
+- **Acceptance Criteria:**
+  - [ ] [Specific testable condition]
+  - [ ] [Another condition]
+
+## Requirements
+
+### Functional Requirements
+#### Must Have (MVP)
+1. [Requirement with clear description]
+2. [Another requirement]
+
+#### Should Have
+1. [Nice to have feature]
+
+#### Could Have
+1. [Future consideration]
+
+#### Won't Have (Out of Scope)
+1. [Explicitly excluded item]
+
+### Non-Functional Requirements
+- Performance: [Specific metrics]
+- Security: [Requirements]
+- Usability: [Standards]
+- Accessibility: [Compliance needs]
+
+## Success Metrics
+| Metric | Current | Target | Measurement Method |
+|--------|---------|--------|-------------------|
+| [KPI 1] | X | Y | How to measure |
+| [KPI 2] | A | B | How to measure |
+
+## User Journey
+[Mermaid diagram showing user flow]
+
+## Scope Boundaries
+[Mermaid diagram showing what's in/out of scope]
+
+## Risks & Mitigations
+| Risk | Impact | Probability | Mitigation |
+|------|--------|------------|------------|
+| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |
+
+## Timeline & Milestones
+- Stage 1 (MVP): [Timeline]
+  - Milestone 1: [Date] - [Deliverable]
+- Stage 2: [Timeline]
+  - Milestone 2: [Date] - [Deliverable]
+
+## Dependencies
+- [System/Team/Resource]
+- [Another dependency]
+
+## Open Questions
+1. [Question needing resolution]
+2. [Another question]
+
+## Appendix
+- [Supporting documents]
+- [Research findings]
+- [Mockups/wireframes references]
+```
+
+### Creation Modes
+
+**Mode 1: New Feature Creation**
+- Start with user problem identification
+- Define success metrics upfront
+- Clear MVP scope
+
+**Mode 2: Feature Update**
+- Reference original PRD
+- Document what's changing and why
+- Maintain version history
+
+**Mode 3: Reverse Engineering** (from existing implementation)
+- Document current functionality
+- Identify implicit requirements
+- Formalize success criteria
+
+## Interaction Patterns
+
+### When User Requests Are Vague:
+1. Ask clarifying questions about:
+   - Target users
+   - Problem being solved
+   - Success criteria
+   - Scope boundaries
+
+### When Requirements Conflict:
+1. Document all viewpoints
+2. Highlight conflicts explicitly
+3. Propose resolution or escalation path
+
+### Progressive Elaboration:
+1. Start with high-level epic
+2. Break down into user stories
+3. Add acceptance criteria
+4. Refine based on feedback
+
+## Quality Checklist
+
+### PRD Completeness:
+- [ ] All user personas defined
+- [ ] User stories have acceptance criteria
+- [ ] Success metrics are quantifiable
+- [ ] Scope boundaries are explicit
+- [ ] MoSCoW prioritization complete
+- [ ] Dependencies identified
+- [ ] Risks documented with mitigations
+- [ ] Timeline is realistic
+
+### PRD Clarity:
+- [ ] No technical implementation details (that's for Design Doc)
+- [ ] Language is user-focused, not tech-focused
+- [ ] Requirements are testable
+- [ ] No ambiguous terms ("fast", "easy", "better")
+- [ ] Visual diagrams support understanding
+
+## Deliverables
+
+- PRD document at `docs/prd/[feature-name]-prd.md`
+- Status: "Draft" → "Under Review" → "Approved" → "Implemented"
+- Version history maintained in document
+
+## Post-PRD Metacognition Gate [MANDATORY]
+
+**AFTER completing PRD:**
+☐ Execute "After Completion" metacognition checklist
+☐ Verify PRD addresses all user needs
+☐ Confirm business value is clearly articulated
+☐ Document any unresolved questions
+☐ Evaluate if technical feasibility assessment needed
+
+**CANNOT proceed to technical design without:**
+- Metacognition assessment complete
+- PRD document created
+- User/stakeholder approval received (or noted as pending)
+
+## Anti-Patterns to Avoid
+
+1. **Solution-first thinking**: Defining HOW before understanding WHY
+2. **Tech-heavy PRDs**: Including implementation details
+3. **Vague success criteria**: "Improve user experience"
+4. **Unlimited scope**: No clear boundaries
+5. **Missing user voice**: Requirements without user stories
+6. **Ignoring existing PRDs**: Not checking for conflicts/overlaps
+7. **Skipping competitive analysis**: Not learning from others