Session Template Applier

⚠️ MANDATORY: Read Project Documentation First

BEFORE applying session templates, you MUST read and understand the following project documentation:

Core Project Documentation

1. README.md - Project overview, features, and getting started
2. AI_DOCS/project-context.md - Tech stack, architecture, development workflow
3. AI_DOCS/code-conventions.md - Code style, formatting, best practices
4. AI_DOCS/tdd-workflow.md - TDD process, testing standards, coverage requirements

Session Context (if available)

5. .ai-context/ACTIVE_TASKS.md - Current tasks and priorities
6. .ai-context/CONVENTIONS.md - Project-specific conventions
7. .ai-context/RECENT_DECISIONS.md - Recent architectural decisions
8. .ai-context/LAST_SESSION_SUMMARY.md - Previous session summary

Additional AI Documentation

9. AI_DOCS/ai-tools.md - Session management workflow (CRITICAL for this skill)
10. AI_DOCS/ai-skills.md - Other specialized skills/agents available

Why This Matters

• Workflow Integration: Understand how ai-update-plan fits into session management
• Template Selection: Choose appropriate template based on project patterns
• Customization: Adapt templates to match project-specific requirements
• Task Context: Consider active tasks and recent decisions when planning

After reading these files, proceed with your template application task below.

Overview

Automatically apply task-specific planning templates to AI sessions, customizing generic steps with task-specific details.

When to Use

• Starting a new AI session with ai-start-task
• Need structured plan for common task types
• Want to ensure all important steps are included
• Standardizing workflow across team
• Complex tasks needing comprehensive planning

Available Templates

1. Feature Development (feature)

For adding new functionality

2. Bug Fix (bugfix)

For fixing existing issues

3. Refactoring (refactor)

For code improvement without behavior changes

4. Documentation (documentation)

For doc updates and improvements

5. Security Fix (security)

For security vulnerabilities and hardening

Usage Examples

Apply Template at Session Start

bash
1# Start session with feature template
2apply feature development template for "Add OAuth2 authentication"

Output: Creates session with:

• Research & design phase
• TDD test-writing phase
• Implementation phase
• Security review phase
• Documentation phase

Apply Template to Existing Session

bash
1# Mid-session, realize you need structured plan
2apply refactoring template for current session

Custom Template Selection

bash
1# Let skill analyze task and choose template
2suggest template for "Fix memory leak in data processor"
3# → Skill suggests: "bugfix" template

Template Structures

Feature Template

File: templates/feature.md

markdown
1### Phase 1: Research & Design
2- [ ] Review related code in the codebase
3- [ ] Identify integration points
4- [ ] Design data models and interfaces
5- [ ] Document API contracts
6- [ ] Consider edge cases and error scenarios
7
8### Phase 2: Write Tests (TDD)
9- [ ] Write tests for happy path scenarios
10- [ ] Write tests for edge cases
11- [ ] Write tests for error handling
12- [ ] Write integration tests
13- [ ] Ensure tests fail initially (red phase)
14
15### Phase 3: Implementation
16- [ ] Implement core functionality
17- [ ] Add error handling
18- [ ] Add input validation
19- [ ] Add logging
20- [ ] Run tests - should pass (green phase)
21
22### Phase 4: Refactoring
23- [ ] Remove duplication (DRY)
24- [ ] Simplify complex logic
25- [ ] Improve naming
26- [ ] Add type hints where missing
27- [ ] Keep tests passing
28
29### Phase 5: Quality Check
30- [ ] Run make check (format, lint, test, security)
31- [ ] Fix all quality issues
32- [ ] Verify coverage ≥ 80%
33- [ ] Review with tdd-reviewer agent
34- [ ] Apply quality-fixer for auto-fixable issues
35
36### Phase 6: Documentation
37- [ ] Update README if user-facing changes
38- [ ] Add/update docstrings
39- [ ] Update API documentation
40- [ ] Add usage examples
41- [ ] Document configuration changes
42
43### Phase 7: Final Review
44- [ ] Review all changes with git diff
45- [ ] Test manually in development
46- [ ] Verify all edge cases work
47- [ ] Check performance implications
48- [ ] Ready for PR/commit

Bugfix Template

File: templates/bugfix.md

markdown
1### Phase 1: Reproduction
2- [ ] Reproduce the bug reliably
3- [ ] Document steps to reproduce
4- [ ] Identify affected components
5- [ ] Check if regression (previously working)
6- [ ] Review related issues
7
8### Phase 2: Root Cause Analysis
9- [ ] Add debug logging
10- [ ] Trace execution flow
11- [ ] Identify exact failure point
12- [ ] Understand why it fails
13- [ ] Document root cause
14
15### Phase 3: Write Reproduction Test (TDD)
16- [ ] Write test that reproduces the bug
17- [ ] Verify test fails (confirms bug exists)
18- [ ] Test should be specific to the bug
19- [ ] Include edge cases related to bug
20- [ ] Document expected vs actual behavior
21
22### Phase 4: Fix Implementation
23- [ ] Implement minimal fix for root cause
24- [ ] Avoid over-engineering the fix
25- [ ] Add defensive checks if needed
26- [ ] Add logging for future debugging
27- [ ] Verify test now passes
28
29### Phase 5: Regression Prevention
30- [ ] Add tests for related scenarios
31- [ ] Check if bug exists elsewhere
32- [ ] Add validation to prevent recurrence
33- [ ] Update error messages if applicable
34- [ ] Document why bug occurred
35
36### Phase 6: Quality & Testing
37- [ ] Run full test suite (no regressions)
38- [ ] Run make check
39- [ ] Verify coverage maintained/improved
40- [ ] Test manually with original report steps
41- [ ] Check performance not degraded
42
43### Phase 7: Documentation
44- [ ] Update changelog
45- [ ] Document fix in commit message
46- [ ] Add code comments explaining fix
47- [ ] Update docs if behavior changed
48- [ ] Reference issue number if applicable

Refactoring Template

File: templates/refactor.md

markdown
1### Phase 1: Establish Safety Net
2- [ ] Ensure tests exist for code being refactored
3- [ ] Run tests - all must pass (baseline)
4- [ ] Run make check - must pass
5- [ ] Commit current state (safety checkpoint)
6- [ ] Document current behavior
7
8### Phase 2: Identify Improvements
9- [ ] Identify code smells (duplication, complexity)
10- [ ] Find violations of SOLID principles
11- [ ] Look for unclear naming
12- [ ] Identify missing abstractions
13- [ ] List specific improvements needed
14
15### Phase 3: Plan Refactoring Steps
16- [ ] Break into small, safe steps
17- [ ] Prioritize by risk/impact
18- [ ] Identify dependencies between steps
19- [ ] Plan to keep tests green throughout
20- [ ] Consider breaking into multiple commits
21
22### Phase 4: Refactor Incrementally
23- [ ] Make one small change at a time
24- [ ] Run tests after each change
25- [ ] Keep tests passing (always green)
26- [ ] Commit after each successful step
27- [ ] If tests fail, revert and adjust approach
28
29### Phase 5: Improve Design
30- [ ] Extract methods/functions
31- [ ] Remove duplication (DRY)
32- [ ] Improve naming (clarity)
33- [ ] Simplify complex conditionals
34- [ ] Add type hints for clarity
35
36### Phase 6: Quality Verification
37- [ ] Run make check (must pass)
38- [ ] Verify no behavior changes
39- [ ] Check performance not degraded
40- [ ] Review with tdd-reviewer agent
41- [ ] Ensure coverage maintained
42
43### Phase 7: Documentation
44- [ ] Update docstrings for changed interfaces
45- [ ] Add comments for complex logic
46- [ ] Document why refactoring was needed
47- [ ] Update architecture docs if applicable
48- [ ] Record design decisions

Documentation Template

File: templates/documentation.md

markdown
1### Phase 1: Content Audit
2- [ ] Review existing documentation
3- [ ] Identify outdated content
4- [ ] Find missing documentation
5- [ ] Check for broken links
6- [ ] Review user feedback/questions
7
8### Phase 2: Content Planning
9- [ ] Define documentation scope
10- [ ] Identify target audience
11- [ ] Plan document structure
12- [ ] Prioritize sections to update
13- [ ] Gather technical details needed
14
15### Phase 3: Write/Update Content
16- [ ] Write clear, concise content
17- [ ] Add code examples
18- [ ] Include usage scenarios
19- [ ] Add diagrams/visuals if helpful
20- [ ] Follow documentation style guide
21
22### Phase 4: Code Examples
23- [ ] Ensure all code examples work
24- [ ] Test code examples actually run
25- [ ] Add comments to examples
26- [ ] Show both basic and advanced usage
27- [ ] Include error handling examples
28
29### Phase 5: Review & Polish
30- [ ] Check spelling and grammar
31- [ ] Verify technical accuracy
32- [ ] Ensure consistent terminology
33- [ ] Check formatting and layout
34- [ ] Validate all links work
35
36### Phase 6: Sync with Code
37- [ ] Update docstrings in code
38- [ ] Ensure API docs match implementation
39- [ ] Update type hints documentation
40- [ ] Sync version numbers
41- [ ] Update changelog
42
43### Phase 7: Validation
44- [ ] Have someone else review
45- [ ] Test following docs from scratch
46- [ ] Verify examples in clean environment
47- [ ] Check docs render correctly
48- [ ] Update AI_DOCS if relevant

Security Fix Template

File: templates/security.md

markdown
1### Phase 1: Vulnerability Assessment
2- [ ] Understand the security issue
3- [ ] Assess severity and impact
4- [ ] Identify affected versions
5- [ ] Check if actively exploited
6- [ ] Review security advisories
7
8### Phase 2: Impact Analysis
9- [ ] Identify all affected code paths
10- [ ] Determine data exposure risk
11- [ ] Check for similar issues elsewhere
12- [ ] Assess authentication/authorization impact
13- [ ] Review compliance implications
14
15### Phase 3: Security Test (TDD)
16- [ ] Write test demonstrating vulnerability
17- [ ] Test should fail (exploits vulnerability)
18- [ ] Test common attack vectors
19- [ ] Test boundary conditions
20- [ ] Document attack scenarios
21
22### Phase 4: Implement Fix
23- [ ] Apply principle of least privilege
24- [ ] Use secure coding practices
25- [ ] Validate all inputs
26- [ ] Sanitize outputs
27- [ ] Add rate limiting if applicable
28
29### Phase 5: Security Hardening
30- [ ] Add additional security checks
31- [ ] Implement defense in depth
32- [ ] Add security logging
33- [ ] Update authentication/authorization
34- [ ] Review encryption/hashing
35
36### Phase 6: Security Testing
37- [ ] Run security scan (Bandit)
38- [ ] Test with malicious inputs
39- [ ] Verify authentication works
40- [ ] Test authorization boundaries
41- [ ] Check for information disclosure
42
43### Phase 7: Security Review
44- [ ] Review with security-focused perspective
45- [ ] Check OWASP Top 10 compliance
46- [ ] Verify no new vulnerabilities introduced
47- [ ] Test error messages don't leak info
48- [ ] Document security measures
49
50### Phase 8: Quality & Documentation
51- [ ] Run make check
52- [ ] Update security documentation
53- [ ] Add security comments in code
54- [ ] Document security assumptions
55- [ ] Plan coordinated disclosure if needed

How It Works

Step 1: Analyze Task Description

Extract keywords to determine task type:

Feature indicators:

• "add", "implement", "create", "build", "new"
• "feature", "functionality", "capability"

Bugfix indicators:

• "fix", "bug", "issue", "error", "broken"
• "crash", "fail", "regression"

Refactor indicators:

• "refactor", "improve", "clean up", "reorganize"
• "simplify", "optimize", "restructure"

Documentation indicators:

• "document", "docs", "README", "guide"
• "explain", "describe", "instructions"

Security indicators:

• "security", "vulnerability", "exploit", "CVE"
• "authentication", "authorization", "XSS", "SQL injection"

Step 2: Load Template

Read appropriate template from templates/ directory:

bash
1# Load template file
2template_file=".claude/skills/session-template/templates/${template_type}.md"
3cat "$template_file"

Step 3: Customize Template

Customize generic steps with task-specific details:

markdown
1# Generic template:
2- [ ] Review related code in the codebase
3
4# Customized for "Add OAuth2 authentication":
5- [ ] Review related authentication code for OAuth2 integration

Step 4: Apply to Session

Use ai-update-plan to add items to the current session:

bash
1# Add each phase item to plan
2uv run ai-update-plan --add "Review related authentication code" --phase "Phase 1"
3uv run ai-update-plan --add "Identify OAuth2 provider integration" --phase "Phase 1"
4# ... etc

Step 5: Display Plan

Show the complete plan with progress tracking:

bash
1uv run ai-update-plan --show

Integration with ai-update-plan

This skill leverages ai-update-plan features:

Add Items by Phase

bash
1# Add to specific phase
2uv run ai-update-plan --add "Write OAuth2 tests" --phase "Phase 2"

Customize After Application

bash
1# Rename generic item to specific
2uv run ai-update-plan --rename "Review related code" \
3  --to "Review existing OAuth implementation"
4
5# Remove irrelevant items
6uv run ai-update-plan --remove "Add diagrams/visuals"

Track Progress

bash
1# Check off completed items
2uv run ai-update-plan "Review related authentication code"
3
4# Show progress
5uv run ai-update-plan --show

Customization Guide

Creating Custom Templates

1. Create new template file in templates/
2. Follow standard phase structure
3. Use checkbox format - [ ]
4. Group related items in phases
5. Include all quality gates

Example custom template:

markdown
1### Phase 1: API Design
2- [ ] Define API endpoints
3- [ ] Document request/response formats
4- [ ] Choose authentication method
5- [ ] Plan rate limiting strategy
6
7### Phase 2: Implementation (TDD)
8- [ ] Write API endpoint tests
9- [ ] Implement endpoints
10- [ ] Add validation middleware
11- [ ] Add error handling
12
13### Phase 3: Integration
14- [ ] Test with client application
15- [ ] Update API documentation
16- [ ] Add usage examples
17- [ ] Deploy to staging

Template Variables

Templates can include placeholders:

markdown
1- [ ] Review {module_name} module
2- [ ] Test {function_name} with various inputs
3- [ ] Update {doc_file} documentation

Skill will replace these based on task description analysis.

Output Format

After applying template:

markdown
1## Session Template Applied: Feature Development
2
3**Template:** feature.md
4**Task:** Add OAuth2 authentication
5**Items Added:** 28
6
7### Plan Structure:
8- Phase 1: Research & Design (5 items)
9- Phase 2: Write Tests (5 items)
10- Phase 3: Implementation (5 items)
11- Phase 4: Refactoring (5 items)
12- Phase 5: Quality Check (4 items)
13- Phase 6: Documentation (3 items)
14- Phase 7: Final Review (5 items)
15
16### Customizations Applied:
17- Replaced "Review related code" → "Review existing authentication for OAuth2"
18- Added "Research OAuth2 providers (Google, GitHub, Auth0)"
19- Added "Test token refresh mechanism"
20- Removed generic placeholder items
21
22### View Your Plan:
23```bash
24uv run ai-update-plan --show

Start Working:

Begin with Phase 1, checking off items as you complete them:

bash
1uv run ai-update-plan "Review existing authentication for OAuth2"

Customize Plan:

Add task-specific items:

bash
1uv run ai-update-plan --add "Test SSO integration" --phase "Phase 2"

Remove irrelevant items:

bash
1uv run ai-update-plan --remove "Generic item"

## Best Practices

1. **Apply template early** - Start session with template for comprehensive planning
2. **Customize immediately** - Adjust generic items to be specific to your task
3. **Remove irrelevant steps** - Don't keep items that don't apply
4. **Add missing steps** - Template is starting point, not gospel
5. **Track progress** - Check off items as you complete them
6. **Update as you learn** - Adjust plan based on discoveries

## Template Selection Guide

**Use "feature" when:**
- Adding new user-facing functionality
- Building new API endpoints
- Creating new modules/components
- Adding new configuration options

**Use "bugfix" when:**
- Fixing reported issues
- Resolving test failures
- Addressing regressions
- Patching security vulnerabilities (minor)

**Use "refactor" when:**
- Improving code structure
- Reducing complexity
- Removing duplication
- Modernizing code patterns

**Use "documentation" when:**
- Updating README
- Writing API docs
- Creating usage guides
- Improving code comments

**Use "security" when:**
- Fixing CVEs
- Hardening authentication
- Addressing OWASP issues
- Implementing security features

## Advanced Features

### Multi-Template Application

For complex tasks, combine templates:

```bash
# Security fix that needs refactoring
apply security template
# Then add refactoring items:
uv run ai-update-plan --add "Refactor auth module for clarity" --phase "Phase 9"

Template Inheritance

Create specialized templates that extend base templates:

markdown
1<!-- templates/api-feature.md -->
2<!-- Extends feature.md with API-specific items -->
3
4### Phase 1: API Research & Design
5- [ ] Review related API endpoints
6- [ ] Define OpenAPI/Swagger spec
7- [ ] Plan versioning strategy
8- [ ] Design request/response schemas
9- [ ] Plan rate limiting
10
11[... rest of feature template ...]

Conditional Sections

Templates can include conditional guidance:

markdown
1### Phase X: Database Changes (if applicable)
2- [ ] Design schema changes
3- [ ] Write migration scripts
4- [ ] Test migration rollback
5- [ ] Update ORM models
6
7*Skip this phase if no database changes needed*

Integration with Other Tools

With ai-start-task

bash
1# Start session and apply template atomically
2uv run ai-start-task "Add OAuth2 authentication" --template=feature

With TDD Reviewer

Template includes TDD-specific phases:

• Phase 2: Write Tests (TDD)
• Phase 5: Quality Check (includes tdd-reviewer)

With Quality Enforcer

Template includes quality gates:

• Phase 5: Quality Check (make check)
• Phase 7: Final Review (quality verification)

Remember

Templates are starting points, not rigid requirements:

• Customize for your specific task
• Add missing items unique to your situation
• Remove items that don't apply
• Adjust phases as you learn more

The goal is structured flexibility - enough structure to ensure quality, enough flexibility to adapt to reality.