thanh-kit 2.5.0

package/templates/skills/plan-analysis/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: plan-analysis
+description: Use when the user provides an implementation plan file and asks to analyze it, assess impact, update specifications, or verify planned changes. Triggers on keywords like "analyze plan", "implementation plan", "assess impact", "update spec from plan", "verify plan".
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task, TodoWrite
+---
+
+# Implementation Plan Analysis & Specification Update
+
+You are to operate as an expert full-stack dotnet angular principle developer, software architect, and technical analyst to analyze a detailed implementation plan, perform comprehensive impact analysis, and update specification documents.
+
+**IMPORTANT**: Always thinks hard, plan step by step to-do list first before execute. Always remember to-do list, never compact or summary it when memory context limit reach. Always preserve and carry your to-do list through every operation.
+
+---
+
+## Core Anti-Hallucination Protocols
+
+### ASSUMPTION_VALIDATION_CHECKPOINT
+Before every major operation:
+1. "What assumptions am I making about [X]?"
+2. "Have I verified this with actual code evidence?"
+3. "Could I be wrong about [specific pattern/relationship]?"
+
+### EVIDENCE_CHAIN_VALIDATION
+Before claiming any relationship:
+- "I believe X calls Y because..." → show actual code
+- "This follows pattern Z because..." → cite specific examples
+- "Service A owns B because..." → grep for actual boundaries
+
+### TOOL_EFFICIENCY_PROTOCOL
+- Batch multiple Grep searches into single calls with OR patterns
+- Use parallel Read operations for related files
+- Combine semantic searches with related keywords
+
+### CONTEXT_ANCHOR_SYSTEM
+Every 10 operations:
+1. Re-read the original task description
+2. Verify the current operation aligns with original goals
+3. Update the `Current Focus` in `## Progress` section
+
+---
+
+## PHASE 1: EXTERNAL MEMORY-DRIVEN IMPLEMENTATION PLAN ANALYSIS
+
+Build a structured knowledge model in `ai_task_analysis_notes/[plan-name].ai_task_analysis_notes_temp.md`.
+
+### PHASE 1A: INITIALIZATION AND DISCOVERY
+
+1. **Initialize** the analysis file with standard headings
+
+### IMPLEMENTATION PLAN COMPREHENSIVE ANALYSIS
+
+**IMPLEMENTATION_PLAN_DEEP_ANALYSIS**: Thorough analysis of the implementation plan file:
+
+1. **Plan Structure Analysis**:
+   - Read and parse the implementation plan completely
+   - Extract all planned features, requirements, and changes
+   - Identify implementation phases and dependencies
+   - Document under `## Implementation Plan Overview`
+
+2. **Requirements Extraction**:
+   - Parse Knowledge Graph from implementation plan
+   - Extract new business requirements
+   - Map functional and non-functional requirements
+   - Identify changed business workflows
+   - Document under `## Extracted Requirements`
+
+3. **Planned Changes Analysis**:
+   - Catalog all planned code changes (new files, modifications, deletions)
+   - Identify affected components, services, and layers
+   - Map file-level changes to business capabilities
+   - Extract integration points
+   - Document under `## Planned Changes Analysis`
+
+4. **Architecture Impact Assessment**:
+   - Analyze how changes affect overall system architecture
+   - Identify CQRS pattern impacts (new Commands/Queries/Events)
+   - Map domain entity changes and repository patterns
+   - Document under `## Architecture Impact Assessment`
+
+5. **Existing Specification Analysis**:
+   - Read and analyze existing specification document structure
+   - Identify current test cases, requirements, entity relationships
+   - Map existing test coverage to planned changes
+   - Document under `## Current Specification Analysis`
+
+**AFFECTED_COMPONENTS_DISCOVERY**: For each planned change, discover:
+- Direct Dependencies
+- Indirect Dependencies
+- Test Coverage Impact
+- API Integration Impact
+- Cross-Service Communication
+- Database Schema Impact
+
+Save to `## Comprehensive File List` with:
+- `filePath`, `changeType`, `relationshipType`, `impactLevel`
+- `serviceContext`, `planContext`, `specificationRelevance`
+
+### PHASE 1B: KNOWLEDGE GRAPH CONSTRUCTION
+
+**IMPORTANT: MUST DO WITH TODO LIST**
+
+For each file, document in `## Knowledge Graph`:
+- Standard fields plus plan-specific:
+- `currentContent`: Existing functionality (if file exists)
+- `plannedChanges`: Specific changes planned
+- `changeImpactAnalysis`: How changes affect other components
+- `testingRequirements`: New test cases needed
+- `specificationMapping`: How component maps to spec sections
+- `testCaseImpact`: Existing test cases needing modification
+
+### PHASE 1C: SPECIFICATION MAPPING ANALYSIS
+
+- **Test Case Mapping**: Which existing test cases are affected
+- **Business Requirement Mapping**: How new requirements relate to existing
+- **Entity Relationship Impact**: Changes to entity relationships
+- **Workflow Integration**: How new workflows integrate with existing
+- **Coverage Gap Analysis**: Areas where new test cases needed
+
+### PHASE 1D: OVERALL ANALYSIS
+
+Write comprehensive summary showing:
+- Complete end-to-end workflows affected
+- Architectural patterns impacted
+- Business logic workflow changes
+- Integration points affected
+- Comprehensive test coverage requirements
+
+---
+
+## PHASE 2: COMPREHENSIVE ANALYSIS AND PLANNING
+
+Generate detailed analysis under these headings:
+
+1. **Implementation Impact Analysis**: Component impact, integration points, data flow changes, platform compliance
+
+2. **Business Logic Analysis**: New business rules, modified workflows, validation requirements
+
+3. **Testing Strategy Analysis**: Test coverage requirements, new test scenarios, regression testing needs
+
+4. **Specification Update Strategy**: How to integrate new requirements, maintain traceability, preserve existing coverage
+
+5. **Rollback and Safety Strategy**: Backup procedures, rollback plan, validation checkpoints
+
+---
+
+## PHASE 3: APPROVAL GATE
+
+**CRITICAL**: Present comprehensive analysis for explicit approval. **DO NOT** proceed without it.
+
+---
+
+## PHASE 4: SPECIFICATION UPDATE EXECUTION
+
+Once approved, execute with MANDATORY steps:
+
+1. **Backup Original Specification**
+2. **Read and Parse Existing Specification**
+3. **Execute Planned Updates**:
+   - New Requirements Integration
+   - Entity Relationship Updates
+   - Test Case Enhancement
+   - Traceability Matrix Updates
+   - Coverage Analysis Updates
+4. **Maintain Specification Structure**
+5. **Quality Assurance Validation**
+
+---
+
+## SUCCESS VALIDATION
+
+Verify under `## Specification Validation`:
+- **Requirements Traceability**: All plan requirements mapped
+- **Test Coverage Validation**: All changes covered by tests
+- **Business Workflow Validation**: End-to-end workflows documented
+- **Integration Testing Coverage**: Cross-service impacts covered
+- **Regression Prevention**: Existing functionality protected
+
+---
+
+## Plan Analysis Guidelines
+
+- **Plan-Driven Analysis**: Base all analysis on the detailed implementation plan
+- **Specification Structure Preservation**: Maintain standardized specification format
+- **Comprehensive Impact Assessment**: Analyze direct and indirect effects
+- **End-to-End Workflow Mapping**: Understand affected business processes
+- **Enterprise Architecture Awareness**: Respect platform patterns
+- **Quality-Focused Testing**: Create comprehensive test specifications
+- **Specification Completeness**: Ensure full traceability
+- **Risk Assessment and Mitigation**: Identify risks and provide rollback strategies
+- **Bidirectional Traceability**: Maintain clear mapping between plan and spec
+- **Coverage Preservation**: Maintain existing test coverage while adding new

package/templates/skills/planning/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: planning
+description: Use when you need to plan technical solutions that are scalable, secure, and maintainable.
+license: MIT
+---
+
+# Planning
+
+Create detailed technical implementation plans through research, codebase analysis, solution design, and comprehensive documentation.
+
+## When to Use
+
+Use this skill when:
+- Planning new feature implementations
+- Architecting system designs
+- Evaluating technical approaches
+- Creating implementation roadmaps
+- Breaking down complex requirements
+- Assessing technical trade-offs
+
+## Core Responsibilities & Rules
+
+Always honoring **YAGNI**, **KISS**, and **DRY** principles.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+### 1. Research & Analysis
+Load: `references/research-phase.md`
+**Skip if:** Provided with researcher reports
+
+### 2. Codebase Understanding
+Load: `references/codebase-understanding.md`
+**Skip if:** Provided with scout reports
+
+### 3. Solution Design
+Load: `references/solution-design.md`
+
+### 4. Plan Creation & Organization
+Load: `references/plan-organization.md`
+
+### 5. Task Breakdown & Output Standards
+Load: `references/output-standards.md`
+
+## Workflow Process
+
+1. **Initial Analysis** → Read codebase docs, understand context
+2. **Research Phase** → Spawn researchers, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan
+6. **Review & Refine** → Ensure completeness, clarity, actionability
+
+## Output Requirements
+
+- DO NOT implement code - only create plans
+- Respond with plan file path and summary
+- Ensure self-contained plans with necessary context
+- Include code snippets/pseudocode when clarifying
+- Provide multiple options with trade-offs when appropriate
+- Fully respect the `./docs/development-rules.md` file.
+
+**Plan Directory Structure**
+```
+plans/
+└── {date}-plan-name/
+    ├── research/
+    │   ├── researcher-XX-report.md
+    │   └── ...
+    ├── reports/
+    │   ├── XX-report.md
+    │   └── ...
+    ├── scout/
+    │   ├── scout-XX-report.md
+    │   └── ...
+    ├── plan.md
+    ├── phase-XX-phase-name-here.md
+    └── ...
+```
+
+## Active Plan State
+
+Prevents version proliferation by tracking current working plan via session state.
+
+### Active vs Suggested Plans
+
+Check the `## Plan Context` section injected by hooks:
+- **"Plan: {path}"** = Active plan, explicitly set via `set-active-plan.cjs` - use for reports
+- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
+- **"Plan: none"** = No active plan
+
+### Rules
+
+1. **If "Plan:" shows a path**: Ask "Continue with existing plan? [Y/n]"
+2. **If "Suggested:" shows a path**: Inform user, ask if they want to activate or create new
+3. **If "Plan: none"**: Create new plan using naming from `## Naming` section
+4. **Update on create**: Run `node .claude/scripts/set-active-plan.cjs {plan-dir}`
+
+### Report Output Location
+
+All agents writing reports MUST:
+1. Check `## Naming` section injected by hooks for the computed naming pattern
+2. Active plans use plan-specific reports path
+3. Suggested plans use default reports path (not plan folder)
+
+**Important:** Suggested plans do NOT get plan-specific reports - this prevents pollution of old plan folders.
+
+## Quality Standards
+
+- Be thorough and specific
+- Consider long-term maintainability
+- Research thoroughly when uncertain
+- Address security and performance concerns
+- Make plans detailed enough for junior developers
+- Validate against existing codebase patterns
+
+**Remember:** Plan quality determines implementation success. Be comprehensive and consider all solution aspects.

package/templates/skills/planning/references/codebase-understanding.md

@@ -0,0 +1,62 @@
+# Codebase Understanding Phase
+
+**When to skip:** If provided with scout reports, skip this phase.
+
+## Core Activities
+
+### Parallel Scout Agents
+- Use `/scout:ext` (preferred) or `/scout` (fallback) slash command to search the codebase for files needed to complete the task
+- Each scout locates files needed for specific task aspects
+- Wait for all scout agents to report back before analysis
+- Efficient for finding relevant code across large codebases
+
+### Essential Documentation Review
+ALWAYS read these files first:
+
+1. **`./docs/development-rules.md`** (IMPORTANT)
+   - File Name Conventions
+   - File Size Management
+   - Development rules and best practices
+   - Code quality standards
+   - Security guidelines
+
+2. **`./docs/codebase-summary.md`**
+   - Project structure and current status
+   - High-level architecture overview
+   - Component relationships
+
+3. **`./docs/code-standards.md`**
+   - Coding conventions and standards
+   - Language-specific patterns
+   - Naming conventions
+
+4. **`./docs/design-guidelines.md`** (if exists)
+   - Design system guidelines
+   - Branding and UI/UX conventions
+   - Component library usage
+
+### Environment Analysis
+- Review development environment setup
+- Analyze dotenv files and configuration
+- Identify required dependencies
+- Understand build and deployment processes
+
+### Pattern Recognition
+- Study existing patterns in codebase
+- Identify conventions and architectural decisions
+- Note consistency in implementation approaches
+- Understand error handling patterns
+
+### Integration Planning
+- Identify how new features integrate with existing architecture
+- Map dependencies between components
+- Understand data flow and state management
+- Consider backward compatibility
+
+## Best Practices
+
+- Start with documentation before diving into code
+- Use scouts for targeted file discovery
+- Document patterns found for consistency
+- Note any inconsistencies or technical debt
+- Consider impact on existing features

package/templates/skills/planning/references/output-standards.md

@@ -0,0 +1,127 @@
+# Output Standards & Quality
+
+## Plan File Format
+
+### YAML Frontmatter (Required for plan.md)
+
+All `plan.md` files MUST include YAML frontmatter at the top:
+
+```yaml
+---
+title: "{Brief plan title}"
+description: "{One-sentence summary for card preview}"
+status: pending  # pending | in-progress | completed | cancelled
+priority: P2     # P1 (High) | P2 (Medium) | P3 (Low)
+effort: 4h       # Estimated total effort
+issue: 74        # GitHub issue number (if applicable)
+branch: kai/feat/feature-name
+tags: [frontend, api]  # Category tags
+created: 2025-12-16
+---
+```
+
+### Auto-Population Rules
+
+When creating plans, auto-populate these fields:
+- **title**: Extract from task description
+- **description**: First sentence of Overview section
+- **status**: Always `pending` for new plans
+- **priority**: From user request or default `P2`
+- **effort**: Sum of phase estimates
+- **issue**: Parse from branch name or context
+- **branch**: Current git branch (`git branch --show-current`)
+- **tags**: Infer from task keywords (e.g., frontend, backend, api, auth)
+- **created**: Today's date in YYYY-MM-DD format
+
+### Tag Vocabulary (Recommended)
+
+Use these predefined tags for consistency:
+- **Type**: `feature`, `bugfix`, `refactor`, `docs`, `infra`
+- **Domain**: `frontend`, `backend`, `database`, `api`, `auth`
+- **Scope**: `critical`, `tech-debt`, `experimental`
+
+## Task Breakdown
+
+- Transform complex requirements into manageable, actionable tasks
+- Each task independently executable with clear dependencies
+- Prioritize by dependencies, risk, business value
+- Eliminate ambiguity in instructions
+- Include specific file paths for all modifications
+- Provide clear acceptance criteria per task
+
+### File Management
+List affected files with:
+- Full paths (not relative)
+- Action type (modify/create/delete)
+- Brief change description
+- Dependencies on other changes
+- Fully respect the `./docs/development-rules.md` file.
+
+## Workflow Process
+
+1. **Initial Analysis** → Read docs, understand context
+2. **Research Phase** → Spawn researchers in parallel, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan in Markdown
+6. **Review & Refine** → Ensure completeness, clarity, actionability
+
+## Output Requirements
+
+### What Planners Do
+- Create plans ONLY (no implementation)
+- Provide plan file path and summary
+- Self-contained plans with necessary context
+- Code snippets/pseudocode when clarifying
+- Multiple options with trade-offs when appropriate
+- Fully respect the `./docs/development-rules.md` file.
+
+### Writing Style
+**IMPORTANT:** Sacrifice grammar for concision
+- Focus clarity over eloquence
+- Use bullets and lists
+- Short sentences
+- Remove unnecessary words
+- Prioritize actionable info
+
+### Unresolved Questions
+**IMPORTANT:** List unresolved questions at end
+- Questions needing clarification
+- Technical decisions requiring input
+- Unknowns impacting implementation
+- Trade-offs requiring business decisions
+
+## Quality Standards
+
+### Thoroughness
+- Thorough and specific in research/planning
+- Consider edge cases, failure modes
+- Think through entire user journey
+- Document all assumptions
+
+### Maintainability
+- Consider long-term maintainability
+- Design for future modifications
+- Document decision rationale
+- Avoid over-engineering
+- Fully respect the `./docs/development-rules.md` file.
+
+### Research Depth
+- When uncertain, research more
+- Multiple options with clear trade-offs
+- Validate against best practices
+- Consider industry standards
+
+### Security & Performance
+- Address all security concerns
+- Identify performance implications
+- Plan for scalability
+- Consider resource constraints
+
+### Implementability
+- Detailed enough for junior developers
+- Validate against existing patterns
+- Ensure codebase standards consistency
+- Provide clear examples
+
+**Remember:** Plan quality determines implementation success. Be comprehensive, consider all solution aspects.

package/templates/skills/planning/references/plan-organization.md

@@ -0,0 +1,150 @@
+# Plan Creation & Organization
+
+## Directory Structure
+
+### Plan Location
+Use `Plan dir:` from `## Naming` section injected by hooks. This is the full computed path.
+
+**Example:** `plans/251101-1505-authentication/` or `ai_docs/feature/MRR-1453/`
+
+### File Organization
+
+```
+{plan-dir}/                                    # From `Plan dir:` in ## Naming
+├── research/
+│   ├── researcher-XX-report.md
+│   └── ...
+├── reports/
+│   ├── scout-report.md
+│   ├── researcher-report.md
+│   └── ...
+├── plan.md                                    # Overview access point
+├── phase-01-setup-environment.md              # Setup environment
+├── phase-02-implement-database.md             # Database models
+├── phase-03-implement-api-endpoints.md        # API endpoints
+├── phase-04-implement-ui-components.md        # UI components
+├── phase-05-implement-authentication.md       # Auth & authorization
+├── phase-06-implement-profile.md              # Profile page
+└── phase-07-write-tests.md                    # Tests
+```
+
+### Active Plan State Tracking
+
+Check the `## Plan Context` section injected by hooks:
+- **"Plan: {path}"** = Active plan - use for reports
+- **"Suggested: {path}"** = Branch-matched, hint only - do NOT auto-use
+- **"Plan: none"** = No active plan
+
+**Pre-Creation Check:**
+1. If "Plan:" shows a path → ask "Continue with existing plan? [Y/n]"
+2. If "Suggested:" shows a path → inform user (hint only, do NOT auto-use)
+3. If "Plan: none" → create new plan using naming from `## Naming` section
+
+**After Creating Plan:**
+```bash
+# Update session state so subagents get the new plan context:
+node .claude/scripts/set-active-plan.cjs {plan-dir}
+```
+
+**Report Output Rules:**
+1. Use `Report:` and `Plan dir:` from `## Naming` section
+2. Active plans use plan-specific reports path
+3. Suggested plans use default reports path to prevent old plan pollution
+
+## File Structure
+
+### Overview Plan (plan.md)
+
+**IMPORTANT:** All plan.md files MUST include YAML frontmatter. See `output-standards.md` for schema.
+
+**Example plan.md structure:**
+```markdown
+---
+title: "Feature Implementation Plan"
+description: "Add user authentication with OAuth2 support"
+status: pending
+priority: P1
+effort: 8h
+issue: 123
+branch: kai/feat/oauth-auth
+tags: [auth, backend, security]
+created: 2025-12-16
+---
+
+# Feature Implementation Plan
+
+## Overview
+
+Brief description of what this plan accomplishes.
+
+## Phases
+
+| # | Phase | Status | Effort | Link |
+|---|-------|--------|--------|------|
+| 1 | Setup | Pending | 2h | [phase-01](./phase-01-setup.md) |
+| 2 | Implementation | Pending | 4h | [phase-02](./phase-02-impl.md) |
+| 3 | Testing | Pending | 2h | [phase-03](./phase-03-test.md) |
+
+## Dependencies
+
+- List key dependencies here
+```
+
+**Guidelines:**
+- Keep generic and under 80 lines
+- List each phase with status/progress
+- Link to detailed phase files
+- Key dependencies
+
+### Phase Files (phase-XX-name.md)
+Fully respect the `./docs/development-rules.md` file.
+Each phase file should contain:
+
+**Context Links**
+- Links to related reports, files, documentation
+
+**Overview**
+- Priority
+- Current status
+- Brief description
+
+**Key Insights**
+- Important findings from research
+- Critical considerations
+
+**Requirements**
+- Functional requirements
+- Non-functional requirements
+
+**Architecture**
+- System design
+- Component interactions
+- Data flow
+
+**Related Code Files**
+- List of files to modify
+- List of files to create
+- List of files to delete
+
+**Implementation Steps**
+- Detailed, numbered steps
+- Specific instructions
+
+**Todo List**
+- Checkbox list for tracking
+
+**Success Criteria**
+- Definition of done
+- Validation methods
+
+**Risk Assessment**
+- Potential issues
+- Mitigation strategies
+
+**Security Considerations**
+- Auth/authorization
+- Data protection
+
+**Next Steps**
+- Dependencies
+- Follow-up tasks

package/templates/skills/planning/references/research-phase.md

@@ -0,0 +1,49 @@
+# Research & Analysis Phase
+
+**When to skip:** If provided with researcher reports, skip this phase.
+
+## Core Activities
+
+### Parallel Researcher Agents
+- Spawn multiple `researcher` agents in parallel to investigate different approaches
+- Wait for all researcher agents to report back before proceeding
+- Each researcher investigates a specific aspect or approach
+
+### Sequential Thinking
+- Use `sequential-thinking` skill for dynamic and reflective problem-solving
+- Structured thinking process for complex analysis
+- Enables multi-step reasoning with revision capability
+
+### Documentation Research
+- Use `docs-seeker` skill to read and understand documentation
+- Research plugins, packages, and frameworks
+- Find latest technical documentation using llms.txt standard
+
+### GitHub Analysis
+- Use `gh` command to read and analyze:
+  - GitHub Actions logs
+  - Pull requests
+  - Issues and discussions
+- Extract relevant technical context from GitHub resources
+
+### Remote Repository Analysis
+When given GitHub repository URL, generate fresh codebase summary:
+```bash
+# usage: 
+repomix --remote <github-repo-url>
+# example: 
+repomix --remote https://github.com/mrgoonie/human-mcp
+```
+
+### Debugger Delegation
+- Delegate to `debugger` agent for root cause analysis
+- Use when investigating complex issues or bugs
+- Debugger agent specializes in diagnostic tasks
+
+## Best Practices
+
+- Research breadth before depth
+- Document findings for synthesis phase
+- Identify multiple approaches for comparison
+- Consider edge cases during research
+- Note security implications early