agentic-code 0.5.1

package/.agents/tasks/work-planning.md

@@ -0,0 +1,239 @@
+# Work Planning
+
+## 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/language/rules.md`
+3. [LOAD IF NOT ACTIVE] `.agents/rules/language/testing.md`
+4. [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 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: CHECK if documentation-criteria.md is active in working memory
+- STEP 7: If documentation-criteria.md NOT active → Execute BLOCKING READ
+- STEP 8: CONFIRM all rules active before proceeding with work planning
+
+## 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)
+   - `.agents/rules/core/documentation-criteria.md` (if not active)
+2. Mark each with "[From work-planning.md]" source tag
+3. Show evidence of injection:
+   ```
+   [PLAN INJECTION FROM work-planning.md]
+   Injected to work plan:
+   ✓ BLOCKING READ: language/rules.md - development standards
+   ✓ BLOCKING READ: language/testing.md - TDD process
+   ✓ BLOCKING READ: documentation-criteria.md - documentation standards
+   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)
+✓ 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 (`work-planning.md`) has been READ and is active
+☐ [VERIFIED] Plan Injection completed (from work-planning.md Plan Injection Requirement)
+☐ [VERIFIED] All required rules listed above are LOADED and active
+☐ [VERIFIED] Work plan contains ALL BLOCKING READs from this file
+☐ [VERIFIED] Design document EXISTS at `docs/design/[feature]-design.md`
+☐ [VERIFIED] User has APPROVED the design
+☐ [VERIFIED] Test skeletons exist (if applicable for test-driven approach)
+☐ [VERIFIED] SESSION_BASELINE_DATE established and active
+
+**METACOGNITION GATE [MANDATORY]:**
+BEFORE creating work plan, execute metacognition assessment:
+- Understand the design intent and goals
+- Verify task decomposition strategy aligns with 1-commit principle
+- Confirm dependencies are logical and achievable
+
+**GATE ENFORCEMENT:**
+IF any box unchecked → HALT → Return to uncompleted step
+IF attempting to skip → CRITICAL ERROR
+
+## Purpose
+
+Create work plans with decomposed tasks.
+
+## When to Use
+
+- Medium/Large scale tasks (3+ files)
+- When user chooses Agentic Coding workflow
+- Refactoring with multiple components
+
+## Completion Conditions [BLOCKING GATES]
+
+☐ [MANDATORY] Work plan document created at `docs/plans/YYYYMMDD-{type}-{description}.md`
+☐ [VERIFIED] Tasks follow 1-COMMIT PRINCIPLE (each task = 1 logical commit)
+☐ [VERIFIED] Dependencies mapped with explicit order
+☐ [VERIFIED] Each task has MEASURABLE completion criteria
+☐ [VERIFIED] Each task has CHECKBOX for progress tracking
+☐ [VERIFIED] Verification command/method specified for EACH task
+☐ [VERIFIED] Risk factors with specific mitigations
+
+**GATE CHECK**: Cannot proceed to implementation until ALL boxes checked
+
+## Execution Guidelines
+
+### 1. Plan Structure
+
+Create work plan with:
+- **Overview**: What's being built/changed
+- **Phases**: Logical groupings of work
+- **Tasks**: Individual implementation units
+- **Dependencies**: What must complete before what
+- **Risks**: Potential issues and mitigations
+- **Test References**: Link to generated test skeletons (if available)
+
+### 2. Task Decomposition Principles [1-COMMIT RULE]
+
+**MANDATORY GRANULARITY - 1 TASK = 1 COMMIT**:
+- Each task MUST represent ONE atomic change
+- Each task MUST be committable independently
+- Each task MUST NOT break the build when completed
+
+**File Count Guidelines**:
+- IDEAL: 1-2 files per task (one focused change)
+- MAXIMUM: 3 files per task (if tightly coupled)
+- PROHIBITED: 4+ files (MUST split into smaller tasks)
+
+**Independence Requirements**:
+- Independently verifiable (has own test/verification)
+- Rollback-safe (can revert without breaking)
+- Self-contained (doesn't leave system in partial state)
+
+**Checkbox Update Protocol [MANDATORY]**:
+- BEFORE starting task: Verify checkbox exists `- [ ]`
+- AFTER completing task: Update checkbox to `- [x]` (standard Markdown)
+- ENFORCEMENT: Unchecked completed tasks = Protocol violation
+- REFERENCE: Link to relevant test skeletons when implementing testable features
+
+### 3. Task Format [MANDATORY TEMPLATE]
+
+```markdown
+## Task N: [Task Name]
+
+### Entry Conditions
+- [ ] Previous dependencies complete
+- [ ] Understand what to build
+- [ ] Ready to follow TDD
+
+### Scope [Max 2 files or split]
+- Files affected: [EXACT file paths]
+- Components: [SPECIFIC names]
+
+### Implementation Steps (TDD + Commit)
+1. RED: Write failing test
+2. GREEN: Write code to pass test
+3. REFACTOR: Improve the code
+4. VERIFY: Run quality checks (0 errors required)
+5. COMMIT: Git commit (following 1-COMMIT principle: 1 task = 1 commit)
+
+### Exit Conditions
+- [ ] Test passes
+- [ ] Quality checks pass with 0 errors (per language/testing.md standards)
+- [ ] Changes committed to git
+- [ ] Task checkbox marked [x] in work plan
+
+### Dependencies
+- Depends on: Task [X]
+- Blocks: Task [Y]
+```
+
+### 4. Ordering Strategy
+
+1. **Foundation first**: Core structures before features
+2. **Dependencies respected**: Prerequisites before dependents
+3. **Testability maintained**: Each step verifiable
+4. **Risk front-loaded**: Complex/uncertain parts early
+
+### 5. Common Patterns
+
+**Feature Implementation**
+```
+Stage 1: Data layer
+- Task 1: Define data models
+- Task 2: Create repositories
+
+Stage 2: Business logic
+- Task 3: Implement services
+- Task 4: Add validation
+
+Stage 3: Interface
+- Task 5: Create API endpoints
+- Task 6: Add error handling
+
+Stage 4: Testing
+- Task 7: Unit tests
+- Task 8: Integration tests
+```
+
+**Refactoring**
+```
+Stage 1: Preparation
+- Task 1: Add tests for current behavior
+- Task 2: Create abstraction layer
+
+Stage 2: Migration
+- Task 3: Implement new structure
+- Task 4: Migrate component by component
+
+Stage 3: Cleanup
+- Task 5: Remove old code
+- Task 6: Update documentation
+```
+
+## Deliverables
+
+Work plan document at `docs/plans/YYYYMMDD-{type}-{description}.md` containing:
+- Task breakdown following 1-commit principle
+- Execution order with dependencies
+- Checkboxes for progress tracking (- [ ] format)
+- Verification methods for each task
+- Risk mitigation strategies
+
+**CRITICAL**: Work plan location MUST be in `docs/plans/` directory
+
+## Quality Criteria
+
+Tasks MUST be:
+- **Atomic**: ONE commit worth of changes
+- **Trackable**: Has checkbox for progress
+- **Measurable**: Clear completion criteria
+- **Testable**: Verification method defined
+- **Ordered**: Dependencies explicitly stated
+- **Right-sized**: 1-2 files (3 max)
+
+**ENFORCEMENT CHECKLIST**:
+☐ Each task can be one commit
+☐ Each task has - [ ] checkbox
+☐ Each task has verification command
+☐ No task exceeds 3 files
+☐ Dependencies clearly marked
+
+## Anti-Patterns
+
+Avoid:
+- Vague tasks ("Improve performance")
+- Giant tasks (10+ files)
+- Circular dependencies
+- Missing verification methods
+- Unclear completion criteria

package/.agents/workflows/agentic-coding.md

@@ -0,0 +1,333 @@
+# Agentic Coding Workflow
+
+**When to use**: Medium/Large scale tasks (3+ files) after task-analysis.md recommendation. User approval required before starting.
+
+Track progress internally - do not update this file.
+
+## Workflow Overview
+
+Execute phases sequentially. For Large scale (6+ files), include PRD phase.
+
+## Phase 0: PRD Creation (Large scale only)
+
+### Pre-Phase Gates [BLOCKING - CANNOT PROCEED WITHOUT]:
+1. **[VERIFY PLAN INJECTION]** Confirm work plan contains ALL required BLOCKING READs for this phase
+   - If missing any: HALT - Return to task-analysis.md Step 8
+2. **[BLOCKING READ]** Execute Read on `.agents/tasks/prd-creation.md`
+3. **[VERIFY]** prd-creation.md is ACTIVE in working memory
+4. **[VERIFY]** All rules required by prd-creation.md are LOADED (per its Required Rules section)
+5. **[VERIFY]** Plan Injection from prd-creation.md completed
+6. **[CONFIRM]** Entry gates in prd-creation.md are satisfied
+
+**ENFORCEMENT**: NO requirements work until prd-creation.md confirmed active and Plan Injection verified
+
+### Internal Checklist:
+```
+□ Target users identified
+□ User stories documented
+□ Success metrics defined
+□ Scope boundaries clear
+□ MoSCoW prioritization complete
+```
+
+### Deliverable:
+- PRD document in `docs/prd/[feature-name]-prd.md`
+
+### Completion Conditions:
+- Business value articulated
+- User requirements clear
+- Success criteria measurable
+
+### STOP POINT: PRD Review [BLOCKING GATE]
+**SYSTEM HALT - CANNOT PROCEED WITHOUT:**
+1. PRD document EXISTS at `docs/prd/[feature]-prd.md`
+2. User EXPLICITLY states approval
+3. All requirements understood
+
+**ENFORCEMENT:**
+- NO technical design until PRD approved
+- VIOLATION = Return to PRD phase
+
+## Phase 1: Requirements Analysis
+
+### Internal Checklist:
+```
+□ User requirements documented
+□ Functional requirements listed
+□ Non-functional requirements identified
+□ Constraints and assumptions noted
+□ Success criteria defined
+```
+
+### Completion Conditions:
+- All aspects of requirements are clear
+- Ambiguities resolved through user questions
+- Scope boundaries defined
+
+## Phase 2: Technical Design
+
+### Pre-Phase Gates [BLOCKING - CANNOT PROCEED WITHOUT]:
+1. **[VERIFY PLAN INJECTION]** Confirm work plan contains ALL required BLOCKING READs for this phase
+   - If missing any: HALT - Return to task-analysis.md Step 8
+2. **[BLOCKING READ]** Execute Read on `.agents/tasks/technical-design.md`
+3. **[VERIFY]** technical-design.md is ACTIVE in working memory
+4. **[VERIFY]** All rules required by technical-design.md are LOADED (per its Required Rules section)
+5. **[CONFIRM]** Entry gates in technical-design.md are satisfied
+
+**ENFORCEMENT**:
+- NO design work until technical-design.md confirmed active
+- NO proceeding without Plan Injection verification for ALL BLOCKING READs
+
+### Pre-Design Requirements:
+```
+□ Check for need of technology decision documentation
+□ Perform existing code investigation
+□ Research latest information online
+□ Document user agreements
+```
+
+### Internal Checklist:
+```
+□ Technology decisions documented if needed (refer to technical-design.md)
+□ Architecture approach selected
+□ Component structure designed
+□ Data flow documented
+□ Integration points identified
+□ Technology choices justified
+□ Error handling strategy defined
+□ References cited with URLs
+```
+
+### Deliverable:
+- Technology decision documents in `docs/adr/` (if needed)
+- Design document in `docs/design/`
+
+### Completion Conditions:
+- Design covers all requirements
+- Technical approach is clear
+- Implementation path is defined
+- Latest best practices researched
+
+### STOP POINT: Design Review [BLOCKING GATE]
+**SYSTEM HALT - CANNOT PROCEED WITHOUT:**
+1. Design document EXISTS at `docs/design/[feature]-design.md`
+2. **[VERIFY COMPLIANCE]** Design doc meets ALL requirements from technical-design.md:
+   - All Completion Conditions from technical-design.md satisfied
+   - All sections required by technical-design.md present
+   - If non-compliant: REJECT - Return to Phase 2
+3. User EXPLICITLY states approval ("yes", "approved", "大丈夫", etc.)
+4. ADR created if new technology introduced
+
+**ENFORCEMENT:**
+- NO implementation code until approval received
+- NO proceeding without full task definition compliance
+- NO skipping even for "simple" changes
+- VIOLATION = Return to design phase
+
+## Phase 3: Acceptance Test Generation
+
+**PHASE ORDERING RATIONALE**: Test skeletons MUST be generated BEFORE work planning. Test structures define verification boundaries that determine task decomposition granularity. Work plans depend on these test specifications to map implementation units to concrete verification points.
+
+### Pre-Phase Gates [BLOCKING - CANNOT PROCEED WITHOUT]:
+1. **[VERIFY PLAN INJECTION]** Confirm work plan contains ALL required BLOCKING READs for this phase
+   - If missing any: HALT - Return to task-analysis.md Step 8
+2. **[BLOCKING READ]** Execute Read on `.agents/tasks/acceptance-test-generation.md`
+3. **[VERIFY]** acceptance-test-generation.md is ACTIVE in working memory
+4. **[VERIFY]** All rules required by acceptance-test-generation.md are LOADED (per its Required Rules section)
+5. **[VERIFY]** Plan Injection from acceptance-test-generation.md completed
+6. **[CONFIRM]** Entry gates in acceptance-test-generation.md are satisfied
+7. **[VERIFY]** Design document EXISTS and contains Acceptance Criteria section
+
+**ENFORCEMENT**: NO test generation until acceptance-test-generation.md confirmed active and Plan Injection verified
+
+### Internal Checklist:
+```
+□ Design document Acceptance Criteria analyzed
+□ Multi-dimensional requirements mapped
+□ Integration test skeletons generated
+□ E2E test skeletons generated
+□ Test priorities assigned using risk analysis
+□ Verification points documented
+□ Traceability matrix created
+□ Edge cases systematically identified
+```
+
+### Deliverable:
+- Integration test skeletons with pending/placeholder markers
+- E2E test skeletons with pending/placeholder markers
+- Traceability matrix linking tests to ACs
+
+### Completion Conditions:
+- All ACs mapped to test cases
+- Test framework conventions followed
+- Test priorities align with business risk
+- Verification points clearly documented
+
+### STOP POINT: Test Skeleton Review [BLOCKING GATE]
+**SYSTEM HALT - CANNOT PROCEED WITHOUT:**
+1. Test skeletons EXIST in appropriate test directories
+2. **[VERIFY COMPLIANCE]** Test generation meets ALL requirements from acceptance-test-generation.md:
+   - All Completion Conditions from acceptance-test-generation.md satisfied
+   - Test framework conventions followed
+   - Traceability matrix complete
+   - If non-compliant: REJECT - Return to Phase 3
+3. User EXPLICITLY states approval on test coverage approach
+4. Generated tests follow existing project patterns
+
+**ENFORCEMENT:**
+- NO work planning until test skeletons approved
+- NO proceeding without test generation compliance
+- VIOLATION = Return to test generation phase
+
+## Phase 4: Work Planning
+
+**PHASE DEPENDENCY**: This phase REQUIRES completed test skeletons from Phase 3. Task decomposition uses test verification points as boundaries for work units. Each implementation task maps to specific test cases for validation.
+
+### Pre-Phase Gates [BLOCKING - CANNOT PROCEED WITHOUT]:
+1. **[VERIFY PLAN INJECTION]** Confirm work plan contains ALL required BLOCKING READs for this phase
+   - If missing any: HALT - Return to task-analysis.md Step 8
+2. **[BLOCKING READ]** Execute Read on `.agents/tasks/work-planning.md`
+3. **[VERIFY]** work-planning.md is ACTIVE in working memory
+4. **[VERIFY]** All rules required by work-planning.md are LOADED (per its Required Rules section)
+5. **[VERIFY]** Plan Injection from work-planning.md completed
+6. **[CONFIRM]** Entry gates in work-planning.md are satisfied
+7. **[VERIFY]** Design document APPROVED by user
+8. **[VERIFY]** Test skeletons from Phase 3 EXIST in test directories
+
+**ENFORCEMENT**: NO work plan creation until work-planning.md confirmed active and Plan Injection verified
+
+### Internal Checklist:
+```
+□ Tasks decomposed into units
+□ Dependencies identified
+□ Execution order determined
+□ Each task has clear completion criteria
+□ Risk factors noted
+```
+
+### Deliverable:
+- Work plan document with task list
+
+### Task Breakdown Format:
+```
+1. [Task Name]
+   - Files affected:
+   - Dependencies:
+   - Completion: When [specific condition]
+   - Status: [ ] Pending
+```
+
+### STOP POINT: Work Plan Approval [BLOCKING GATE]
+**SYSTEM HALT - CANNOT WRITE CODE WITHOUT:**
+1. Work plan document EXISTS at `docs/plans/YYYYMMDD-{type}-{description}.md`
+2. **[VERIFY INJECTION]** Plan MUST contain ALL BLOCKING READs identified in task-analysis Step 8:
+   - Every BLOCKING READ from workflow phases
+   - Every BLOCKING READ from task definitions
+   - Every BLOCKING READ from required rules
+   - Each marked with source: "[From Plan Injection]"
+3. Each task has MEASURABLE completion criteria
+4. User EXPLICITLY approves plan
+
+**GATE VERIFICATION:**
+```
+Plan Location: docs/plans/[filename].md
+Task Count: [N] tasks defined
+BLOCKING READs in plan: [count] items
+Plan Injection Status: [COMPLETE/INCOMPLETE]
+User Approval: [AWAITING/RECEIVED]
+```
+
+**ENFORCEMENT:**
+- First line of code PROHIBITED until approval
+- Missing ANY BLOCKING READ = Return to task-analysis Step 8
+
+## Phase 5: Implementation
+
+### Pre-Implementation Gates [BLOCKING - CANNOT START WITHOUT]:
+```
+1. [VERIFY PLAN INJECTION] Confirm work plan contains ALL required BLOCKING READs for this phase
+   - If missing any: HALT - Return to task-analysis.md Step 8
+2. [BLOCKING READ] Execute Read on `.agents/tasks/implementation.md`
+3. [VERIFY] implementation.md is ACTIVE in working memory
+4. [VERIFY] All rules required by implementation.md are LOADED (per its Required Rules section)
+5. [VERIFY] Plan Injection from implementation.md completed
+6. [CONFIRM] Entry gates in implementation.md are satisfied
+7. [VERIFY] Work plan document EXISTS and has been APPROVED
+8. [CONFIRM] Current task identified from work plan
+```
+
+**CRITICAL ENFORCEMENT**:
+- ZERO lines of code until implementation.md confirmed active
+- First code attempt without gates = IMMEDIATE DELETION
+- Violation logged and requires restart from Phase 5 gates
+
+### Execution Pattern [ENFORCED SEQUENCE]:
+```
+For each task in work plan:
+  1. [METACOGNITION PRE] Execute "When Starting Work" checklist from metacognition protocol
+  2. [TRACKING] Mark task as in_progress in task tracking
+  3. [IMPLEMENT] Write code following ALL loaded rules (TDD: RED-GREEN-REFACTOR)
+  4. [VERIFY] Run ALL quality check commands - MUST have 0 errors
+  5. [COMMIT] Git commit with descriptive message for this task
+  6. [UPDATE] Mark task checkbox complete [x] in work plan document
+  7. [GATE CHECK] ALL completion criteria must pass
+  8. [METACOGNITION POST] Execute "After Completion" checklist
+  9. [TRACKING] Mark task complete in task tracking
+  10. [CHECKPOINT] Cannot start next task until all steps complete
+```
+
+**ENFORCEMENT:**
+- Skipping ANY step = RESTART task
+- No code without implementation.md loaded
+- No task transition without metacognition
+
+### Guidelines:
+- Complete one task fully before starting next
+- Test each component as implemented
+- Document significant decisions
+- Ask user when blocked
+
+## Phase 6: Quality Assurance
+
+### Pre-Phase Gates [BLOCKING - CANNOT PROCEED WITHOUT]:
+1. **[VERIFY PLAN INJECTION]** Confirm work plan contains ALL required BLOCKING READs for this phase
+   - If missing any: HALT - Return to task-analysis.md Step 8
+2. **[BLOCKING READ]** Execute Read on `.agents/tasks/quality-assurance.md`
+3. **[VERIFY]** quality-assurance.md is ACTIVE in working memory
+4. **[VERIFY]** All rules required by quality-assurance.md are LOADED (per its Required Rules section)
+5. **[VERIFY]** Plan Injection from quality-assurance.md completed
+6. **[CONFIRM]** All implementation tasks marked complete in work plan
+
+**ENFORCEMENT**: NO quality checks until quality-assurance.md confirmed active and Plan Injection verified
+
+### Internal Checklist:
+```
+□ All tasks completed
+□ Build succeeds
+□ Tests pass
+□ Linting clean
+□ Documentation updated
+□ Edge cases handled
+```
+
+### Completion Conditions:
+- All quality standards met
+- No known bugs remain
+- Code is production-ready
+
+## Phase 7: Review and Handoff
+
+### Internal Checklist:
+```
+□ Implementation matches design
+□ All requirements fulfilled
+□ Documentation complete
+□ Known limitations documented
+□ Setup instructions provided
+```
+
+### Final Deliverables:
+- Working implementation
+- Updated documentation
+- Test suite
+- Setup/deployment instructions