Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,26 @@
+{
+  "name": "cc-arsenal",
+  "description": "Security-focused AI agents, quality automation commands, and safety hooks for Claude Code",
+  "version": "1.0.0",
+  "author": {
+    "name": "Giovani Moutinho",
+    "email": "contact@giovani.dev"
+  },
+  "skills": [
+    "./skills/skill-creator/",
+    "./skills/jira-cli/"
+  ],
+  "commands": [
+    "./commands/docs/adr.md",
+    "./commands/docs/check.md",
+    "./commands/docs/diagram.md",
+    "./commands/docs/init.md",
+    "./commands/docs/rfc.md",
+    "./commands/docs/update.md",
+    "./commands/git/commit.md",
+    "./commands/git/create-pr.md"
+  ],
+  "hooks": [
+    "./hooks/hooks.json"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# cc-arsenal
+
+Security-focused AI agents, quality automation commands, and safety hooks for Claude Code

commands/docs/adr.md

@@ -0,0 +1,217 @@
+---
+description: "Create numbered ADR documenting architectural decision"
+argument-hint: "<title> [variant]"
+allowed-tools: ["Read", "Write", "Grep", "Glob"]
+---
+
+# Create Architecture Decision Record
+
+Create a new Architecture Decision Record (ADR) documenting an architectural decision.
+
+## Your Task
+
+1. **Parse Arguments**:
+   - Extract decision title from `$ARGUMENTS`
+   - Check for variant keyword: `lightweight`, `full`, or `madr`
+   - If variant found, remove it from title
+   - Default variant: `nygard` (Nygard style)
+
+2. **Determine ADR Number**:
+   - Scan `docs/adr/` directory
+   - Find highest existing ADR number (format: `XXXX-*`)
+   - Increment by 1
+   - If no ADRs exist, start with `0001`
+   - Format as 4-digit padded number (e.g., `0001`, `0023`)
+
+3. **Sanitize Title for Filename**:
+   - Convert title to kebab-case
+   - Remove special characters
+   - Lowercase all letters
+   - Example: "Use Redis for Caching" → `use-redis-for-caching`
+
+4. **Gather Context**:
+   - Search codebase for relevant information about the decision topic
+   - Look for related code, configs, or documentation
+   - Understand current state and alternatives
+   - Keep context concise but informative
+
+5. **Load Template**:
+   - Template location: `commands/docs/templates/adr/`
+   - Select based on variant:
+     - `nygard` → `nygard.md` (default)
+     - `lightweight` → `lightweight.md`
+     - `full` → `full.md`
+     - `madr` → `madr.md`
+
+6. **Populate Template**:
+   Replace placeholders:
+   - `{{ADR_NUMBER}}` - 4-digit number
+   - `{{ADR_TITLE}}` - Original title (Title Case)
+   - `{{DATE}}` - Current date (YYYY-MM-DD)
+   - `{{CONTEXT}}` - Gathered context from codebase
+   - `{{PROJECT_NAME}}` - Git repo or directory name
+
+7. **Create ADR File**:
+   - Filename: `docs/adr/XXXX-kebab-case-title.md`
+   - Ensure `docs/adr/` directory exists
+   - Write populated content
+   - Set initial status to "Proposed"
+
+8. **Report Creation**:
+   - Show ADR number and title
+   - Display file path
+   - Provide next steps
+
+## Template Variants
+
+### Nygard Style (Default)
+Michael Nygard's ADR format - concise and focused.
+
+**Sections:**
+- Title with number
+- Status
+- Context
+- Decision
+- Consequences
+
+**Use when:** Most decisions, balanced detail
+
+### Lightweight
+Minimal ADR for quick decisions.
+
+**Sections:**
+- Title with number
+- Status
+- Decision
+- Rationale
+
+**Use when:** Simple, straightforward decisions
+
+### Full
+Comprehensive ADR with detailed sections.
+
+**Sections:**
+- Title with number
+- Status
+- Context
+- Decision Drivers
+- Considered Options
+- Decision
+- Consequences (Positive, Negative, Neutral)
+- Pros and Cons
+- Related Decisions
+- References
+
+**Use when:** Complex, high-impact decisions
+
+### MADR
+Markdown Architectural Decision Records format.
+
+**Sections:**
+- Title with number
+- Status
+- Context and Problem Statement
+- Decision Drivers
+- Considered Options
+- Decision Outcome
+- Consequences
+
+**Use when:** Following MADR standard
+
+## Usage
+
+Basic ADR creation (uses Nygard template):
+```
+/docs:adr "Database Migration Strategy"
+/docs:adr "API Authentication Approach"
+/docs:adr "Microservices Communication Pattern"
+```
+
+With template variant override:
+```
+/docs:adr lightweight "Use Redis for Session Storage"
+/docs:adr full "Adopt Event-Driven Architecture"
+/docs:adr madr "Select Database Technology"
+```
+
+## ADR Numbering
+
+- **First ADR**: `0001-record-architecture-decisions.md` (meta-ADR)
+- **Subsequent ADRs**: Auto-incremented (0002, 0003, etc.)
+- **Format**: `XXXX-kebab-case-title.md`
+
+## ADR Status Lifecycle
+
+Update status in the ADR as the decision progresses:
+
+1. **Proposed** - Initial proposal (default)
+2. **Accepted** - Decision approved
+3. **Deprecated** - No longer recommended
+4. **Superseded** - Replaced by another ADR
+
+## Context Gathering Examples
+
+```bash
+# For database decisions
+!`find . -name "*.sql" -o -name "*models.py" -o -name "*schema.prisma" | head -10`
+
+# For API decisions
+!`grep -r "router\|endpoint\|api" --include="*.py" --include="*.ts" --include="*.js" . | head -20`
+
+# For architecture decisions
+!`find . -name "docker-compose.yml" -o -name "*.config.js" -o -name "*.config.ts" | head -10`
+```
+
+## Important Notes
+
+- **One Decision per ADR**: Keep focused on a single decision
+- **Context Matters**: Include "why" even if it seems obvious
+- **Link Related ADRs**: Reference superseded or related decisions
+- **Early Documentation**: Create ADRs early in decision process
+- **Imperative Language**: Use "we will" not "we should"
+- **Status Updates**: Update status as decision progresses
+
+## Example Output
+
+```
+Architecture Decision Record Created ✓
+
+ADR-0006: Use Redis for Session Storage
+File: docs/adr/0006-use-redis-for-session-storage.md
+Status: Proposed
+Template: Nygard Style
+
+Next Steps:
+  1. Review and refine the decision context
+  2. Fill in consequences (positive/negative)
+  3. Discuss with team
+  4. Update status to "Accepted" when approved
+  5. Reference this ADR in related code/docs
+```
+
+## When to Create ADRs
+
+Create an ADR when making:
+- Technology stack decisions
+- Architecture pattern choices
+- Database or storage decisions
+- API design choices
+- Security architecture decisions
+- Deployment strategy decisions
+- Major library/framework selections
+- Cross-cutting concerns (logging, caching, etc.)
+
+## Best Practices
+
+- **Create early**: Document decisions before implementation
+- **Be honest**: Document the real reasons, not ideal reasons
+- **Include alternatives**: Show what was considered
+- **Accept trade-offs**: Acknowledge negative consequences
+- **Link to code**: Reference implementation in the ADR
+- **Review regularly**: Revisit ADRs during retrospectives
+- **Update status**: Keep status current as decisions evolve
+
+---
+
+**Template Location**: `commands/docs/templates/adr/`
+**Output Directory**: `docs/adr/`

commands/docs/check.md

@@ -0,0 +1,268 @@
+---
+description: "Validate documentation freshness, completeness, and quality"
+argument-hint: "[focus]"
+allowed-tools: ["Read", "Grep", "Glob", "Bash(git *, find *)"]
+---
+
+# Check Documentation Quality
+
+Validate documentation freshness, completeness, and quality against current codebase state.
+
+## Your Task
+
+1. **Parse Arguments**:
+   - Extract optional focus area from `$ARGUMENTS`
+   - Focus areas: `core`, `data`, `infrastructure`, `all`
+   - Default: check all documentation
+
+2. **Scan Documentation**:
+   - Find all documentation files in `docs/`
+   - Identify documentation types present
+   - Check for ADRs and RFCs
+
+3. **Analyze Project** (determine what docs should exist):
+   - Technology stack detection
+   - Database presence
+   - Deployment configurations
+   - Project type (library, app, service)
+
+4. **Perform Validation Checks**:
+
+   **A. Relevance Check**:
+   - Determine which docs are relevant to this project
+   - Identify missing documentation for detected technologies
+   - Example: If database models found, should have data-model.md
+
+   **B. Freshness Check**:
+   - Compare doc last-modified dates with related code changes
+   - Use git to check recent changes:
+   ```bash
+   # Check when files were last modified
+   !`git log -1 --format="%ai" -- docs/architecture.md 2>/dev/null`
+
+   # Check recent changes to codebase
+   !`git log --since="7 days ago" --oneline --name-only | head -50`
+   ```
+   - Flag docs that haven't been updated after significant code changes
+
+   **C. Completeness Check**:
+   - Verify all required sections are present
+   - Check for unreplaced placeholders: `{{PLACEHOLDER}}`
+   - Ensure diagrams exist where expected
+   - Verify ADRs have all sections (Status, Context, Decision)
+   - Verify RFCs have all sections (Summary, Motivation, Proposal)
+
+   **D. Quality Check**:
+   - Validate Mermaid diagram syntax
+   - Check for broken internal links (references to non-existent files)
+   - Verify markdown formatting
+   - Check for empty sections
+
+5. **Calculate Scores**:
+
+   **Freshness Scoring** (per document):
+   - Fresh (90-100): Updated within last 7 days or no related code changes
+   - Good (70-89): Minor code changes since last update
+   - Stale (50-69): Significant code changes since last update
+   - Outdated (<50): Major code changes or very old
+
+   **Completeness Scoring** (per document):
+   - Complete (90-100): All sections present, no placeholders
+   - Good (70-89): Most sections present, minor gaps
+   - Incomplete (50-69): Several missing sections
+   - Poor (<50): Major sections missing
+
+   **Quality Scoring** (per document):
+   - Excellent (90-100): No issues, all diagrams valid
+   - Good (70-89): Minor formatting issues
+   - Fair (50-69): Several issues
+   - Poor (<50): Major problems, broken diagrams
+
+   **Overall Score**:
+   - Average of all document scores
+   - Weight by importance (core docs > others)
+
+6. **Generate Report**:
+   - Status summary with overall score
+   - List of documents by status (Good, Needs Attention, Missing)
+   - Quality issues with specific locations
+   - Actionable recommendations
+
+## Validation Checks Detail
+
+### Missing Documentation
+```bash
+# Check for expected docs
+!`ls -1 docs/ 2>/dev/null | grep -E "architecture|onboarding|data-model|deployment"`
+
+# Check for ADRs
+!`ls -1 docs/adr/*.md 2>/dev/null | wc -l`
+
+# Check for RFCs
+!`ls -1 docs/rfc/*.md 2>/dev/null | wc -l`
+```
+
+### Stale Documentation
+```bash
+# Get last modification date of docs
+!`find docs -name "*.md" -exec stat -f "%Sm %N" -t "%Y-%m-%d" {} \; 2>/dev/null || find docs -name "*.md" -exec stat -c "%y %n" {} \;`
+
+# Get recent code changes
+!`git log --since="30 days ago" --name-only --pretty=format: | sort -u | grep -v "^$" | head -30`
+```
+
+### Placeholder Check
+```bash
+# Find unreplaced placeholders
+!`grep -r "{{.*}}" docs/ --include="*.md" 2>/dev/null`
+```
+
+### Broken Links
+```bash
+# Find markdown links
+!`grep -r "\[.*\](" docs/ --include="*.md" -h | grep -o "\[.*\](.*)" | head -20`
+```
+
+## Usage
+
+Check all documentation:
+```
+/docs:check
+```
+
+With specific focus:
+```
+/docs:check core
+/docs:check data
+/docs:check focus on database documentation
+```
+
+Quick check:
+```
+/docs:check quick
+```
+
+## Output Format
+
+### Status Summary
+```
+Documentation Health Report
+
+Overall Score: 85/100
+
+✅ Good (3 docs):
+  • docs/architecture.md (Score: 95/100)
+    - Last updated: 2 days ago
+    - All sections complete
+    - Diagrams valid
+
+  • docs/onboarding.md (Score: 92/100)
+    - Last updated: 1 week ago
+    - Comprehensive and current
+
+  • docs/adr/ (5 records, Score: 88/100)
+    - All ADRs properly formatted
+    - Recent decisions documented
+
+⚠️ Needs Attention (2 docs):
+  • docs/data-model.md (Score: 65/100)
+    - Outdated: Models changed 5 days ago (docs/data-model.md:1)
+    - Missing ER diagram
+    → Recommendation: Run /docs:diagram er
+
+  • docs/deployment.md (Score: 58/100)
+    - Missing deployment steps for new services
+    - Placeholder not replaced: {{DEPLOYMENT_STEPS}} (line 42)
+    → Recommendation: Run /docs:update deployment
+
+❌ Missing (2 docs):
+  • docs/security.md
+    - Security middleware detected but not documented
+    → Recommendation: Run /docs:init or /docs:diagram security
+
+  • docs/api-documentation.md
+    - 15 API endpoints found but not documented
+    → Recommendation: Run /docs:init
+
+🔧 Quality Issues:
+  • docs/data-model.md:42 - Invalid Mermaid syntax
+  • docs/architecture.md:15 - Broken link to [non-existent.md]
+  • docs/deployment.md:23 - Unreplaced placeholder {{DEPLOYMENT_STEPS}}
+```
+
+### Detailed Report
+
+For each documentation file:
+- **Filename and path**
+- **Score breakdown** (Freshness + Completeness + Quality)
+- **Last Updated**: Timestamp
+- **Specific Issues**: With line numbers
+- **Recommendations**: Actionable next steps with commands
+
+## Recommendations Format
+
+Based on findings, suggest specific actions:
+
+```
+Priority Recommendations:
+
+1. HIGH: Update data model documentation
+   Command: /docs:diagram er
+   Reason: Schema changed 5 days ago, ER diagram missing
+
+2. MEDIUM: Fix deployment documentation placeholders
+   Command: /docs:update deployment
+   Reason: Contains unreplaced placeholders
+
+3. LOW: Add security documentation
+   Command: /docs:diagram security
+   Reason: Good practice for complete documentation
+```
+
+## Important Notes
+
+- **Non-destructive**: Only reads, never modifies documentation
+- **Git-aware**: Uses git history to assess freshness
+- **Context-aware**: Understands project type and relevant docs
+- **Actionable**: Provides specific commands to fix issues
+- **Incremental**: Can be run frequently
+
+## Example Checks
+
+### Core Documentation
+- architecture.md exists and current?
+- onboarding.md exists and comprehensive?
+- ADRs directory exists with properly formatted ADRs?
+
+### Data Documentation
+- data-model.md exists if database detected?
+- ER diagrams present and valid?
+- Schema matches current models?
+
+### Infrastructure Documentation
+- deployment.md exists if Docker/K8s detected?
+- Security.md exists?
+- Dependencies documented?
+
+## When to Run
+
+Run this command:
+- Before onboarding new team members
+- During documentation reviews
+- After major refactoring
+- As part of pre-release checklist
+- When documentation feels stale
+- Regularly (weekly or bi-weekly)
+
+## Best Practices
+
+- **Run regularly**: Make it part of your workflow
+- **Address issues**: Don't let documentation debt accumulate
+- **Automate**: Consider running in CI for documentation PRs
+- **Prioritize**: Fix high-impact issues first
+- **Track scores**: Monitor documentation health over time
+
+---
+
+**Dependencies**: Requires git for freshness checking
+**Output**: Comprehensive health report with scores and recommendations

commands/docs/diagram.md

@@ -0,0 +1,327 @@
+---
+description: "Generate Mermaid diagrams from codebase analysis"
+argument-hint: "<type> [context]"
+allowed-tools: ["Read", "Write", "Grep", "Glob"]
+---
+
+# Generate System Diagrams
+
+Generate Mermaid diagrams including architecture, database schema, deployment, and security architecture.
+
+## Your Task
+
+1. **Parse Arguments**:
+   - Extract diagram type from `$ARGUMENTS`
+   - Supported types: `er`, `arch`, `deployment`, `security`
+   - Extract optional context (remaining arguments)
+
+2. **Validate Diagram Type**:
+   - If type not provided or invalid, show available types
+   - Exit with helpful message
+
+3. **Analyze Codebase** (based on diagram type):
+
+   **For ER Diagrams (`er`)**:
+   - Find ORM model files
+   - Supported ORMs:
+     - Python: SQLAlchemy, Django, Tortoise, SQLModel, Peewee
+     - JS/TS: Prisma, TypeORM, Sequelize, Mongoose
+     - Other: GORM (Go), ActiveRecord (Ruby)
+   - Extract:
+     - Tables/entities
+     - Columns with types
+     - Relationships (one-to-one, one-to-many, many-to-many)
+     - Constraints (PK, FK, unique)
+
+   **For Architecture Diagrams (`arch`)**:
+   - Identify major components
+   - Find services, APIs, workers
+   - Detect queues, caches, databases
+   - Map data flow between components
+   - Identify external dependencies
+
+   **For Deployment Diagrams (`deployment`)**:
+   - Find deployment configs (docker-compose, k8s, etc.)
+   - Identify services and their relationships
+   - Map CI/CD pipeline
+   - Document environment configurations
+
+   **For Security Diagrams (`security`)**:
+   - Find authentication/authorization code
+   - Map security boundaries
+   - Identify data encryption points
+   - Document security controls
+
+4. **Generate Mermaid Diagram**:
+   - Create appropriate Mermaid syntax based on type
+   - Include meaningful labels and relationships
+   - Add comments for clarity
+   - Keep diagram readable (not too complex)
+
+5. **Load Template**:
+   - Template location: `commands/docs/templates/`
+   - Select based on diagram type:
+     - `er` → `data-model.md`
+     - `arch` → `architecture.md`
+     - `deployment` → `deployment.md`
+     - `security` → `security.md`
+
+6. **Populate Template**:
+   Replace placeholders:
+   - `{{PROJECT_NAME}}` - Git repo or directory name
+   - `{{DATE}}` - Current date
+   - `{{ER_DIAGRAM}}` or `{{DIAGRAM_CONTENT}}` - Generated Mermaid code
+   - `{{ENTITIES}}` or `{{COMPONENTS}}` - Entity/component descriptions
+   - Other diagram-specific placeholders
+
+7. **Create or Update Documentation**:
+   - Output to appropriate file in `docs/`
+   - If file exists, ask before overwriting
+   - Preserve custom content if possible
+
+8. **Report Results**:
+   - Show diagram type and output file
+   - Display summary of what was detected
+   - Provide next steps
+
+## Supported Diagram Types
+
+### ER Diagram (`er`)
+**Output**: `docs/data-model.md`
+
+Entity-Relationship diagram from database models.
+
+**Detects**:
+- Tables and entities
+- Columns with data types
+- Primary keys
+- Foreign keys
+- Relationships
+- Constraints
+
+**Mermaid syntax**:
+```mermaid
+erDiagram
+    USER ||--o| PROFILE : "has"
+    USER {
+        uuid id PK
+        string email UK
+        string password_hash
+    }
+    PROFILE {
+        uuid id PK
+        uuid user_id FK
+        string bio
+    }
+```
+
+### Architecture Diagram (`arch`)
+**Output**: `docs/architecture.md`
+
+System architecture and component relationships.
+
+**Detects**:
+- Services and modules
+- API endpoints
+- Databases
+- Caches
+- Message queues
+- External services
+
+**Mermaid syntax**:
+```mermaid
+graph TB
+    Client[Web Client]
+    API[API Server]
+    DB[(Database)]
+    Cache[(Redis)]
+
+    Client --> API
+    API --> DB
+    API --> Cache
+```
+
+### Deployment Diagram (`deployment`)
+**Output**: `docs/deployment.md`
+
+Deployment infrastructure and CI/CD.
+
+**Detects**:
+- Docker containers
+- Kubernetes resources
+- Cloud services
+- CI/CD pipeline stages
+- Environment configurations
+
+**Mermaid syntax**:
+```mermaid
+graph LR
+    Dev[Development]
+    CI[CI Pipeline]
+    Stage[Staging]
+    Prod[Production]
+
+    Dev --> CI
+    CI --> Stage
+    Stage --> Prod
+```
+
+### Security Diagram (`security`)
+**Output**: `docs/security.md`
+
+Security architecture and data flow.
+
+**Detects**:
+- Authentication flows
+- Authorization boundaries
+- Encryption points
+- Security controls
+- Trust boundaries
+
+**Mermaid syntax**:
+```mermaid
+graph TB
+    User[User]
+    Auth[Auth Service]
+    API[Protected API]
+    DB[(Encrypted DB)]
+
+    User -->|JWT| Auth
+    Auth -->|Validated| API
+    API -->|TLS| DB
+```
+
+## Usage
+
+Generate specific diagram type:
+```
+/docs:diagram er
+/docs:diagram arch
+/docs:diagram deployment
+/docs:diagram security
+```
+
+With additional context:
+```
+/docs:diagram er for user and order tables
+/docs:diagram arch for microservices architecture
+/docs:diagram deployment with Docker and Kubernetes
+```
+
+Show available types:
+```
+/docs:diagram
+```
+
+## ORM Detection Examples
+
+### Python ORMs
+```bash
+# SQLAlchemy
+!`find . -name "*models.py" -exec grep -l "Base\|Column\|relationship" {} \; | head -10`
+
+# Django
+!`find . -name "models.py" -exec grep -l "models.Model" {} \; | head -10`
+
+# Tortoise ORM
+!`find . -name "*.py" -exec grep -l "tortoise.models" {} \; | head -10`
+```
+
+### JavaScript/TypeScript ORMs
+```bash
+# Prisma
+!`find . -name "schema.prisma"`
+
+# TypeORM
+!`find . -name "*.entity.ts" -o -name "*entity.js" | head -10`
+
+# Sequelize
+!`find . -name "*.model.js" -o -name "*.model.ts" | head -10`
+```
+
+## Architecture Detection Examples
+
+```bash
+# Find services
+!`find . -name "*service*.ts" -o -name "*service*.py" -o -name "*service*.js" | head -15`
+
+# Find API routes
+!`find . -name "*router*.ts" -o -name "*routes*.py" -o -name "*controller*.js" | head -15`
+
+# Find configs
+!`find . -name "*.config.js" -o -name "*.config.ts" -o -name "config.py" | head -10`
+```
+
+## Deployment Detection Examples
+
+```bash
+# Docker
+!`find . -name "Dockerfile" -o -name "docker-compose.yml" -o -name "docker-compose.yaml"`
+
+# Kubernetes
+!`find . -name "*.k8s.yaml" -o -name "*.k8s.yml" -o -name "*deployment.yaml"`
+
+# CI/CD
+!`find . -name ".github/workflows/*.yml" -o -name ".gitlab-ci.yml" -o -name "Jenkinsfile"`
+```
+
+## Important Notes
+
+- **Auto-detection**: Diagrams generated from actual code
+- **Mermaid format**: Uses GitHub-compatible Mermaid syntax
+- **Readable diagrams**: Limits complexity for clarity
+- **Incremental**: Can regenerate as code evolves
+- **Template-based**: Uses templates for consistent formatting
+- **Context-aware**: Uses optional context to guide generation
+
+## Example Output
+
+```
+ER Diagram Generated ✓
+
+Detected: 5 entities, 12 relationships
+File: docs/data-model.md
+
+Entities Found:
+  ✓ User (SQLAlchemy model)
+  ✓ Profile (SQLAlchemy model)
+  ✓ Role (SQLAlchemy model)
+  ✓ Permission (SQLAlchemy model)
+  ✓ UserRole (junction table)
+
+Relationships:
+  ✓ User → Profile (one-to-one)
+  ✓ User → UserRole (one-to-many)
+  ✓ Role → UserRole (one-to-many)
+  ✓ Role → Permission (many-to-many)
+
+Next Steps:
+  1. Review generated ER diagram
+  2. Add entity descriptions if needed
+  3. Update when schema changes
+  4. Reference in architecture docs
+```
+
+## When to Run
+
+Run when:
+- Database schema has been modified (`er`)
+- Architecture has evolved (`arch`)
+- Deployment configuration changed (`deployment`)
+- Security architecture modified (`security`)
+- Onboarding new team members (all diagrams)
+- Documentation review (all diagrams)
+
+## Best Practices
+
+- **Keep current**: Regenerate after significant changes
+- **Review generated**: Always review auto-generated content
+- **Add context**: Supplement with manual descriptions
+- **Link diagrams**: Reference diagrams in related docs
+- **Version control**: Commit diagram updates with code changes
+- **Simplify**: Break complex diagrams into multiple views
+
+---
+
+**Template Location**: `commands/docs/templates/`
+**Output Directory**: `docs/`

commands/docs/init.md

@@ -0,0 +1,155 @@
+---
+description: "Initialize comprehensive documentation structure for project"
+argument-hint: "[context]"
+allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash(git *)"]
+---
+
+# Initialize Project Documentation
+
+Generate comprehensive documentation structure for your project based on detected technologies and configuration.
+
+## Your Task
+
+1. **Detect Project Characteristics**:
+   - Technology stack (language, frameworks, databases)
+   - Project type (web app, CLI, library, microservice, etc.)
+   - Infrastructure (Docker, K8s, cloud configs)
+   - Database/ORM presence (SQLAlchemy, Prisma, TypeORM, Django, etc.)
+
+2. **Determine Relevant Documentation**:
+   - **Core Documentation** (always generate):
+     - `docs/architecture.md` - System architecture overview
+     - `docs/onboarding.md` - Developer onboarding guide
+     - `docs/adr/0001-record-architecture-decisions.md` - First ADR (meta-ADR)
+
+   - **Data Documentation** (if database detected):
+     - `docs/data-model.md` - Database schema & ER diagrams
+
+   - **Infrastructure Documentation** (if deployment configs found):
+     - `docs/deployment.md` - CI/CD & deployment procedures
+     - `docs/security.md` - Security architecture
+
+   - **Development Documentation** (if collaborative project):
+     - `docs/contributing.md` - Contribution guidelines
+     - `docs/rfc/` - RFC directory for proposals
+
+3. **Check for Existing Documentation**:
+   - Scan `docs/` directory
+   - If files exist, ask user before overwriting
+   - Show what will be created vs what exists
+
+4. **Load Templates**:
+   - Templates are in `commands/docs/templates/`
+   - Use appropriate template for each document type
+   - Replace placeholders with project-specific values
+
+5. **Generate Documentation**:
+   - Create `docs/` directory if it doesn't exist
+   - Create subdirectories: `docs/adr/`, `docs/rfc/` (if needed)
+   - Generate each relevant documentation file
+   - Populate with project-specific content
+
+6. **Template Placeholders**:
+   Replace these in templates:
+   - `{{PROJECT_NAME}}` - From git repo name or directory name
+   - `{{DATE}}` - Current date (YYYY-MM-DD format)
+   - `{{TECH_STACK}}` - Detected technologies
+   - `{{DESCRIPTION}}` - Brief project description from README or git
+   - `{{CONTEXT}}` - Gathered context from codebase analysis
+
+7. **Report Results**:
+   - List all documentation files created
+   - Show what was skipped (already exists)
+   - Provide next steps
+
+## Context Detection Examples
+
+### Technology Stack
+```bash
+# Check for language/framework
+!`find . -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" | head -5`
+
+# Check for database
+!`find . -name "*models.py" -o -name "*schema.prisma" -o -name "*entity.ts" | head -5`
+
+# Check for infrastructure
+!`find . -name "Dockerfile" -o -name "docker-compose.yml" -o -name "*.k8s.yaml" | head -5`
+```
+
+### Project Information
+```bash
+# Get project name
+!`basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)`
+
+# Get project description
+!`head -20 README.md 2>/dev/null || echo ""`
+```
+
+## Usage
+
+Basic initialization (auto-detect everything):
+```
+/docs:init
+```
+
+With additional context:
+```
+/docs:init for Python FastAPI microservice
+/docs:init for Next.js SaaS application
+/docs:init for React component library
+```
+
+## Template Locations
+
+Templates are loaded from `commands/docs/templates/`:
+
+| Document Type | Template File |
+|--------------|---------------|
+| Architecture | `architecture.md` |
+| Onboarding | `onboarding.md` |
+| ADR (first) | `adr/nygard.md` |
+| Data Model | `data-model.md` |
+| Deployment | `deployment.md` |
+| Security | `security.md` |
+| Contributing | `contributing.md` |
+
+## Important Notes
+
+- **Zero-config**: Works without any configuration file
+- **Smart detection**: Only generates relevant documentation
+- **Safe**: Always asks before overwriting existing files
+- **Customizable**: User context in command is used to enhance generation
+- **Git-aware**: Uses git information when available
+- **Incremental**: Can be run multiple times safely
+
+## Example Output
+
+```
+Documentation Initialization Complete ✓
+
+Created:
+  ✓ docs/architecture.md - System architecture overview
+  ✓ docs/onboarding.md - Developer onboarding guide
+  ✓ docs/adr/0001-record-architecture-decisions.md - Meta-ADR
+  ✓ docs/data-model.md - Database schema (SQLAlchemy detected)
+  ✓ docs/deployment.md - Deployment guide (Docker detected)
+
+Skipped (already exists):
+  ⊘ docs/contributing.md
+
+Next Steps:
+  1. Review and customize generated documentation
+  2. Run /docs:diagram er to generate ER diagram
+  3. Run /docs:diagram arch to generate architecture diagram
+  4. Create ADRs for key decisions: /docs:adr "Decision Title"
+```
+
+## When to Run
+
+Run this command when:
+- Starting a new project
+- Adding documentation to an existing project
+- Reorganizing project documentation
+- Onboarding new team members
+
+**Note**: You can run this command multiple times. It will only create missing files and ask before overwriting existing ones.

commands/docs/rfc.md

@@ -0,0 +1,258 @@
+---
+description: "Create numbered RFC for proposing and discussing changes"
+argument-hint: "<title> [variant]"
+allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash(git *)"]
+---
+
+# Create Request For Comments
+
+Create a new RFC (Request For Comments) document for proposing and discussing changes.
+
+## Your Task
+
+1. **Parse Arguments**:
+   - Extract proposal title from `$ARGUMENTS`
+   - Check for variant keyword: `minimal`, `standard`, or `detailed`
+   - If variant found, remove it from title
+   - Default variant: `standard`
+
+2. **Determine RFC Number**:
+   - Scan `docs/rfc/` directory
+   - Find highest existing RFC number (format: `RFC-XXXX-*`)
+   - Increment by 1
+   - If no RFCs exist, start with `0001`
+   - Format as 4-digit padded number (e.g., `0001`, `0023`)
+
+3. **Sanitize Title for Filename**:
+   - Convert title to kebab-case
+   - Remove special characters
+   - Lowercase all letters
+   - Example: "Add GraphQL API Support" → `add-graphql-api-support`
+
+4. **Gather Context**:
+   - Analyze codebase to understand current state
+   - Identify relevant files and patterns
+   - Find similar implementations or related features
+   - Understand technical constraints
+
+5. **Get Author Information**:
+   ```bash
+   # Try to get git author
+   !`git config user.name 2>/dev/null || echo "Development Team"`
+   ```
+
+6. **Load Template**:
+   - Template location: `commands/docs/templates/rfc/`
+   - Select based on variant:
+     - `minimal` → `minimal.md`
+     - `standard` → `standard.md` (default)
+     - `detailed` → `detailed.md`
+
+7. **Populate Template**:
+   Replace placeholders:
+   - `{{RFC_NUMBER}}` - 4-digit number
+   - `{{RFC_TITLE}}` - Original title (Title Case)
+   - `{{DATE}}` - Current date (YYYY-MM-DD)
+   - `{{AUTHOR}}` - Git user name or "Development Team"
+   - `{{CONTEXT}}` - Gathered context from codebase
+   - `{{PROJECT_NAME}}` - Git repo or directory name
+
+8. **Create RFC File**:
+   - Filename: `docs/rfc/RFC-XXXX-kebab-case-title.md`
+   - Ensure `docs/rfc/` directory exists
+   - Write populated content
+   - Set initial status to "Draft"
+
+9. **Report Creation**:
+   - Show RFC number and title
+   - Display file path
+   - Provide workflow guidance
+
+## Template Variants
+
+### Minimal Template
+Quick proposal format for small changes.
+
+**Sections:**
+- Summary
+- Motivation
+- Proposal
+- Open Questions
+
+**Use when:** Small features, minor changes
+
+### Standard Template (Default)
+Balanced RFC for most changes.
+
+**Sections:**
+- Summary
+- Motivation
+- Proposal
+- Rationale and Alternatives
+- Implementation Plan
+- Testing Plan
+- Migration Strategy
+- Open Questions
+- Timeline
+
+**Use when:** Most feature proposals
+
+### Detailed Template
+Comprehensive RFC for major changes.
+
+**Sections:**
+- Summary
+- Background and Motivation
+- Goals and Non-Goals
+- Proposal
+- Detailed Design
+- Rationale and Alternatives
+- Implementation Plan
+- Testing and Quality Assurance
+- Migration and Rollout Strategy
+- Monitoring and Metrics
+- Security Considerations
+- Performance Implications
+- Open Questions and Risks
+- Timeline and Milestones
+- Appendices
+
+**Use when:** Major features, architectural changes
+
+## Usage
+
+Basic RFC creation (uses Standard template):
+```
+/docs:rfc "Add GraphQL API Support"
+/docs:rfc "Implement Rate Limiting"
+/docs:rfc "Add Multi-Tenancy Support"
+```
+
+With template variant override:
+```
+/docs:rfc minimal "Update Logging Format"
+/docs:rfc detailed "Migration to Microservices Architecture"
+/docs:rfc detailed "Adopt Event Sourcing Pattern"
+```
+
+## RFC Status Lifecycle
+
+Update status in the RFC as it progresses:
+
+1. **Draft** - Initial proposal, gathering feedback
+2. **In Review** - Under discussion, modifications being made
+3. **Accepted** - Approved for implementation
+4. **Implemented** - Changes have been deployed
+5. **Rejected** - Not moving forward with proposal
+6. **Withdrawn** - Author withdrew the proposal
+
+## RFC Workflow
+
+### 1. Create RFC
+```
+/docs:rfc "Proposal Title"
+```
+
+### 2. Initial Draft
+- Write comprehensive proposal
+- Include motivation and context
+- Document alternatives considered
+- Add implementation plan
+
+### 3. Share for Feedback
+- Share RFC with team
+- Update status to "In Review"
+- Collect feedback in comments or discussions
+
+### 4. Iterate
+- Incorporate feedback
+- Update proposal as needed
+- Address concerns and questions
+- Refine implementation details
+
+### 5. Final Decision
+- Stakeholders review final version
+- Update status to "Accepted" or "Rejected"
+- Document decision rationale
+
+### 6. Implementation
+- Reference RFC in PRs
+- Update RFC with implementation notes
+- Mark status as "Implemented" when complete
+
+## Context Gathering Examples
+
+```bash
+# For API changes
+!`find . -name "*router*" -o -name "*controller*" -o -name "*api*" | head -10`
+
+# For feature additions
+!`grep -r "export.*function\|export.*class" --include="*.ts" --include="*.js" . | head -20`
+
+# For infrastructure changes
+!`find . -name "*.yml" -o -name "*.yaml" -o -name "Dockerfile" | head -10`
+
+# For performance changes
+!`grep -r "cache\|redis\|memcache\|performance" --include="*.py" --include="*.ts" . | head -15`
+```
+
+## Important Notes
+
+- **Write Before Implementing**: Create RFCs before starting work
+- **Concrete Examples**: Include real code examples when possible
+- **Address Concerns**: Proactively address potential objections
+- **Update Actively**: RFC is a living document during review
+- **Link Related Work**: Reference ADRs, issues, or other RFCs
+- **Clear Language**: Keep accessible to all stakeholders
+- **Define Success**: Include measurable success criteria
+
+## Example Output
+
+```
+Request For Comments Created ✓
+
+RFC-0003: Add GraphQL API Support
+File: docs/rfc/RFC-0003-add-graphql-api-support.md
+Status: Draft
+Template: Standard
+Author: Jane Developer
+
+Next Steps:
+  1. Complete the proposal sections
+  2. Add implementation timeline
+  3. Document testing strategy
+  4. Share with team for feedback
+  5. Update status to "In Review"
+  6. Address feedback and iterate
+  7. Get stakeholder approval
+```
+
+## When to Create RFCs
+
+Create an RFC when proposing:
+- Major feature additions
+- Significant refactorings
+- Architecture changes
+- Breaking API changes
+- New technology adoptions
+- Process changes
+- Performance optimizations with trade-offs
+- Security enhancements
+- Developer experience improvements
+
+## Best Practices
+
+- **Early Documentation**: Write RFC before implementation
+- **Be Specific**: Include concrete examples and details
+- **Show Your Work**: Document research and investigation
+- **Consider Alternatives**: Show what else was considered and why
+- **Realistic Timeline**: Include reasonable milestones
+- **Risk Assessment**: Document known risks and mitigation
+- **Stakeholder Input**: Identify who should review
+- **Clear Outcomes**: Define what success looks like
+- **Keep Updated**: Reflect changes made during review
+
+---
+
+**Template Location**: `commands/docs/templates/rfc/`
+**Output Directory**: `docs/rfc/`

commands/docs/update.md

@@ -0,0 +1,308 @@
+---
+description: "Update documentation by syncing with current codebase state"
+argument-hint: "[all|<doc-name>|category:<name>]"
+allowed-tools: ["Read", "Write", "Grep", "Glob", "Bash(git *)"]
+---
+
+# Update Documentation
+
+Synchronize documentation with the current codebase state. Can update all docs, specific files, or entire categories.
+
+## Your Task
+
+1. **Parse Arguments**:
+   - Extract update mode from `$ARGUMENTS`
+   - Modes:
+     - No args or `all` → Update all relevant docs
+     - `<doc-name>` → Update specific doc (e.g., `architecture`)
+     - `category:<name>` → Update category (e.g., `category:data`)
+   - Default: Update all
+
+2. **Determine Update Scope**:
+
+   **For "all" mode**:
+   - Analyze entire project
+   - Identify all relevant documentation types
+   - Update everything that exists or should exist
+
+   **For specific doc mode**:
+   - Validate doc name
+   - Find the corresponding file
+   - Update only that document
+
+   **For category mode**:
+   - Parse category name: `core`, `data`, `infrastructure`, `development`
+   - Identify all docs in that category
+   - Update all docs in the category
+
+3. **Analyze Codebase**:
+   - Detect technology stack
+   - Find database models (for data docs)
+   - Find deployment configs (for infrastructure docs)
+   - Identify services and components (for architecture)
+   - Check for recent code changes
+
+4. **Check Documentation Freshness**:
+   ```bash
+   # For each doc, compare with related code changes
+   !`git log --since="$(git log -1 --format=%ai docs/architecture.md)" --oneline --name-only | head -30`
+   ```
+   - Identify which docs are outdated
+   - Prioritize updates
+
+5. **Load Templates**:
+   - Template location: `commands/docs/templates/`
+   - Load appropriate templates based on docs being updated
+
+6. **Update Each Document**:
+   - Re-analyze relevant parts of codebase
+   - Regenerate diagrams if needed
+   - Update content while preserving custom sections
+   - Replace placeholders with current values
+
+7. **Preserve Custom Content** (Important):
+   - Keep manually added sections
+   - Preserve non-template content
+   - Only update auto-generated parts
+   - If unsure, ask before overwriting
+
+8. **Report Results**:
+   - List documents updated
+   - List documents skipped (up to date)
+   - List documents created (if missing)
+   - Show summary of changes
+
+## Documentation Categories
+
+### Core Documentation
+Files that are always relevant:
+- `docs/architecture.md` - System architecture
+- `docs/onboarding.md` - Developer onboarding
+- `docs/adr/` - Architecture Decision Records
+
+**Update when**: Architecture changes, setup process changes
+
+### Data Documentation
+Files relevant if database detected:
+- `docs/data-model.md` - Database schema & ER diagrams
+
+**Update when**: Schema changes, models modified
+
+### Infrastructure Documentation
+Files relevant if deployment configs detected:
+- `docs/deployment.md` - CI/CD & deployment
+- `docs/security.md` - Security architecture
+
+**Update when**: Infrastructure changes, security updates
+
+### Development Documentation
+Files relevant for collaborative projects:
+- `docs/contributing.md` - Contribution guidelines
+- `docs/rfc/` - RFC documents
+- `docs/api-documentation.md` - API documentation
+
+**Update when**: Process changes, API changes
+
+## Usage
+
+Update all documentation:
+```
+/docs:update
+/docs:update all
+```
+
+Update specific document:
+```
+/docs:update architecture
+/docs:update data-model
+/docs:update onboarding
+/docs:update deployment
+/docs:update security
+```
+
+Update entire category:
+```
+/docs:update category:core
+/docs:update category:data
+/docs:update category:infrastructure
+/docs:update category:development
+```
+
+With context:
+```
+/docs:update architecture after microservices refactor
+/docs:update data-model after schema migration
+/docs:update category:core for onboarding review
+```
+
+## Document Name Mapping
+
+| Argument        | File Path                  |
+|----------------|----------------------------|
+| `architecture` | `docs/architecture.md`     |
+| `onboarding`   | `docs/onboarding.md`       |
+| `data-model`   | `docs/data-model.md`       |
+| `deployment`   | `docs/deployment.md`       |
+| `security`     | `docs/security.md`         |
+| `contributing` | `docs/contributing.md`     |
+| `api-docs`     | `docs/api-documentation.md`|
+
+## Update Process Detail
+
+### For Architecture Documentation
+1. Scan for services, modules, components
+2. Identify databases, caches, queues
+3. Map data flow
+4. Generate architecture diagram
+5. Update component descriptions
+6. Preserve custom architecture notes
+
+### For Data Model Documentation
+1. Find ORM models
+2. Extract entities and relationships
+3. Generate ER diagram
+4. Document constraints
+5. Update entity descriptions
+6. Preserve custom data notes
+
+### For Deployment Documentation
+1. Find Docker/K8s configs
+2. Map services to infrastructure
+3. Document CI/CD pipeline
+4. Update environment configurations
+5. Preserve custom deployment notes
+
+### For Security Documentation
+1. Find auth/authz code
+2. Map security boundaries
+3. Document encryption points
+4. Identify security controls
+5. Preserve custom security notes
+
+## Change Detection
+
+```bash
+# Check what changed since last doc update
+!`git log --since="$(git log -1 --format=%ai docs/architecture.md 2>/dev/null || echo '30 days ago')" --oneline`
+
+# Find modified source files
+!`git diff --name-only HEAD@{7.days.ago}..HEAD 2>/dev/null | grep -E "\.(py|ts|js|java|go)$" | head -20`
+
+# Check for new files
+!`git log --since="7 days ago" --diff-filter=A --name-only --pretty=format: | sort -u | head -20`
+```
+
+## Template Placeholder Replacement
+
+Replace these placeholders during update:
+- `{{PROJECT_NAME}}` - Current project name
+- `{{DATE}}` - Current date
+- `{{TECH_STACK}}` - Detected technologies
+- `{{ER_DIAGRAM}}` - Generated ER diagram
+- `{{ARCHITECTURE_DIAGRAM}}` - Generated architecture diagram
+- `{{ENTITIES}}` - Extracted entity descriptions
+- `{{COMPONENTS}}` - Extracted component descriptions
+
+## Important Notes
+
+- **Preserves custom content**: Doesn't blindly overwrite
+- **Smart updates**: Only updates outdated sections
+- **Diagram regeneration**: Auto-regenerates diagrams
+- **Git-aware**: Uses git to detect what changed
+- **Safe**: Asks before major changes
+- **Incremental**: Can be run frequently
+
+## Example Output
+
+### All Docs Update
+```
+Documentation Update Complete ✓
+
+Updated (4 docs):
+  ✓ docs/architecture.md (new microservices added)
+  ✓ docs/data-model.md (schema changed, ER diagram regenerated)
+  ✓ docs/deployment.md (K8s config updated)
+  ✓ docs/adr/ (meta-ADR updated)
+
+Up to Date (2 docs):
+  • docs/onboarding.md (no changes needed)
+  • docs/security.md (no changes needed)
+
+Created (1 doc):
+  + docs/contributing.md (collaborative project detected)
+
+Changes Summary:
+  - 3 diagrams regenerated
+  - 12 sections updated
+  - 1 new document created
+  - 0 manual sections affected
+```
+
+### Specific Doc Update
+```
+Architecture Documentation Updated ✓
+
+File: docs/architecture.md
+
+Changes:
+  ✓ Added 2 new services (AuthService, NotificationService)
+  ✓ Updated architecture diagram
+  ✓ Documented new message queue integration
+  ✓ Preserved custom deployment notes
+
+Detected:
+  - 5 services total
+  - 3 databases (PostgreSQL, Redis, MongoDB)
+  - 2 message queues (RabbitMQ, Kafka)
+  - 8 external API integrations
+
+Diagram: Updated with latest component relationships
+```
+
+### Category Update
+```
+Core Documentation Category Updated ✓
+
+Updated (3 docs):
+  ✓ docs/architecture.md
+  ✓ docs/onboarding.md
+  ✓ docs/adr/ (5 records)
+
+Changes:
+  - Architecture: Added microservices diagram
+  - Onboarding: Updated setup instructions for new tooling
+  - ADRs: Verified all properly formatted
+
+Next Steps:
+  1. Review updated documentation
+  2. Consider updating diagrams: /docs:diagram arch
+  3. Create new ADR for recent decision: /docs:adr "Decision Title"
+```
+
+## When to Run
+
+Run this command:
+- After major refactoring
+- When database schema changes
+- After adding new features or components
+- Before onboarding new team members
+- When documentation becomes stale
+- As part of release process
+- After infrastructure changes
+- Before documentation reviews
+
+## Best Practices
+
+- **Run regularly**: Keep documentation current
+- **Review changes**: Always review auto-generated updates
+- **Preserve custom**: Keep manual additions safe
+- **Commit with code**: Update docs alongside code changes
+- **Be specific**: Use specific doc names for targeted updates
+- **Bulk updates**: Use category updates for efficiency
+- **Verify diagrams**: Check generated diagrams for accuracy
+
+---
+
+**Template Location**: `commands/docs/templates/`
+**Output Directory**: `docs/`
+**Safe Mode**: Always preserves custom content

commands/git/commit.md

@@ -0,0 +1,64 @@
+---
+description: "Generate conventional commits following conventionalcommits.org specification"
+argument-hint: ""
+allowed-tools: ["Bash(git *)", "Read", "Edit", "Write"]
+---
+
+# Conventional Commit Command
+
+Generate a conventional commit message following https://www.conventionalcommits.org/en/v1.0.0/ specification and create commits automatically.
+
+## Your Task
+
+1. **Analyze Changes**: Run `git status` and `git diff --staged` to understand current changes
+2. **Group Related Changes**: Identify logically separate changes that should be committed individually (e.g., separate feature additions from bug fixes, documentation updates from code changes)
+3. **For Each Logical Group**:
+  - Determine the appropriate commit type:
+    - `feat`: New feature for the user
+    - `fix`: Bug fix for the user
+    - `docs`: Documentation only changes
+    - `style`: Code style changes (formatting, missing semi-colons, etc.)
+    - `refactor`: Code change that neither fixes a bug nor adds a feature
+    - `perf`: Performance improvements
+    - `test`: Adding missing tests or correcting existing tests
+    - `build`: Changes to build system or external dependencies
+    - `ci`: Changes to CI configuration files and scripts
+    - `chore`: Other changes that don't modify src or test files
+    - `revert`: Reverts a previous commit
+  - Identify the scope if applicable (component, module, or area affected)
+  - Write a concise description in imperative mood (max 50 characters)
+  - Add a detailed body if the change is complex (wrap at 72 characters)
+  - Include breaking change footer if applicable: `BREAKING CHANGE: description`
+  - Format as: `type(scope): description`
+
+4. **Commit Strategy**:
+  - If changes represent a single logical unit: create one commit
+  - If changes span multiple concerns: create separate commits for each logical group
+  - Stage files appropriately for each commit using `git add`
+  - Create each commit with the generated message
+
+## Example Formats
+
+```
+feat(auth): add OAuth2 login support
+fix(api): resolve null pointer in user endpoint
+docs: update installation instructions
+chore(deps): bump lodash to 4.17.21
+refactor(parser): extract validation logic to separate module
+
+feat(shopping-cart)!: remove deprecated calculate() method
+
+BREAKING CHANGE: calculate() has been removed, use computeTotal() instead
+```
+
+## Important Notes
+
+- **Multiple Commits**: If you identify different types of changes (e.g., feat + fix + docs), create separate commits for each type
+- **Staging**: Use `git add <specific-files>` to stage only relevant files for each commit
+- **Imperative Mood**: Use "add" not "added", "fix" not "fixed"
+- **Breaking Changes**: Append an exclamation mark after type/scope and add a `BREAKING CHANGE:` footer
+- **Scope**: Optional but recommended for clarity (e.g., component name, module name)
+- **Body**: Use for complex changes to explain the "what" and "why", not "how"
+- **Pre-commit Hooks**: NEVER use `--no-verify` to skip pre-commit hooks - it's a bad practice that bypasses important quality gates
+
+Generate the most appropriate commit message(s) based on the changes and commit automatically. Ask for confirmation before committing if the changes are complex or span multiple concerns.

commands/git/create-pr.md

@@ -0,0 +1,136 @@
+---
+description: "Create a PR with conventional commit format and pre-filled template"
+argument-hint: "[--base branch] [--draft]"
+allowed-tools: ["Bash(git *)", "Bash(gh *)", "Read", "Write"]
+---
+
+# Create Pull Request Command
+
+Create a GitHub Pull Request following conventional commits specification, pre-filled with the PR template, and opened in the browser for final review.
+
+## Your Task
+
+1. **Validate Preconditions**:
+  - Check working tree is clean: `git status --porcelain`
+  - Get current branch: `git branch --show-current`
+  - Verify branch is not main/master
+  - Check commits exist: `git log origin/<base>..HEAD --oneline`
+  - Extract ticket ID from branch name (e.g., `ABC-123` from `feature/ABC-123_description`)
+  - Display compact validation summary (max 60 chars per line)
+
+2. **Determine Base Branch**:
+  - Use `--base` argument if provided
+  - Otherwise use: `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
+  - Fall back to `main` if detection fails
+
+3. **Analyze Changes**:
+  - Run `git log origin/<base>..HEAD --format="%h %s"` to get commits
+  - Run `git diff origin/<base>...HEAD --stat` for file changes
+  - Identify primary change type for PR title
+
+4. **Generate PR Title** (Conventional Commit Format):
+  - Format: `type(scope): [TICKET-123] description` (max 72 chars)
+  - Or: `type(scope): description` (if no ticket)
+  - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
+  - Examples:
+    - `feat(auth): [ABC-123] add OAuth2 login support`
+    - `fix(api): resolve null pointer in user endpoint`
+
+5. **Fill PR Template**:
+  - Look for `.github/pull_request_template.md`
+  - Fill based on commits and changes
+  - Save to `/tmp/pr-body-$(date +%s).md`
+  - If no template, use:
+    ```markdown
+    ## Summary
+    [Brief description]
+
+    ## Changes
+    - [Bullet points from commits]
+
+    ## Testing
+    - [ ] Tests added/updated
+    - [ ] Manual testing completed
+    ```
+
+6. **Ask for Confirmation**:
+  - Show compact summary with ticket, commits count, authors
+  - Display preview of generated PR title
+  - Display preview of generated PR body
+  - Ask: `Create PR? (y/n/e to edit):`
+  - Accept: `y`, `yes`, `n`, `no`, `e`, `edit`
+  - On `e`: ask for custom title/body modifications
+
+7. **Push and Create PR** (after user confirms):
+  - **CRITICAL Step 1**: Push branch FIRST: `git push -u origin <branch>`
+  - **Step 2**: Create temp body file with timestamp variable
+  - **Step 3**: Open PR in browser with --web (for user to finish):
+    ```bash
+    # Push first (MUST DO THIS)
+    git push -u origin $(git branch --show-current)
+
+    # Create temp body file (capture timestamp in variable)
+    BODY_FILE="/tmp/pr-body-$(date +%s).md"
+    cat > "$BODY_FILE" << 'EOF'
+    ## Summary
+    [Your generated content here]
+    EOF
+
+    # Open in browser with pre-filled data (use determined base branch)
+    # Add --draft if user specified --draft or -d flag
+    gh pr create \
+      --title "type(scope): [TICKET] description" \
+      --body-file "$BODY_FILE" \
+      --base <determined-base-branch> \
+      --web
+    ```
+  - **CRITICAL**: DO NOT use --reviewer, --assignee, or --label with --web (they conflict!)
+  - User will add reviewers/labels in the web UI
+  - Display: "Opening PR in browser for final review..."
+
+## Argument Parsing
+
+Parse optional arguments from the command invocation:
+- `--base branch` or `-b branch` (target branch, defaults to repo default)
+- `--draft` or `-d` (if present, add `--draft` flag to gh pr create command)
+
+**Note**: Reviewers, labels, and assignees must be added in the web UI due to gh CLI limitations with --web flag.
+
+## Important Notes
+
+- **Template Preservation**: Fill the existing PR template WITHOUT changing its structure
+- **Conventional Commits**: PR title MUST follow conventional commit format
+- **Ticket Integration**: Extract ticket number from branch name (patterns: `ABC-123`, `PROJ-456`, etc.) and place after type/scope
+- **Browser Review**: Always use `--web` to let user finalize the PR
+- **Multiple Commits**: Summarize all commits in the PR, focus on the overall change
+- **Breaking Changes**: Clearly indicate if the PR contains breaking changes
+
+## Output Format
+
+**Validation Summary** (keep lines under 60 chars):
+```
+✅ Branch: feature/ABC-123-add-authentication
+✅ Ticket: ABC-123 (In Progress)
+✅ Commits: 8 commits ready
+⚠️ Authors: Multiple authors detected
+
+Create PR? (y/n/e to edit):
+```
+
+## Examples
+
+```bash
+# Simple PR (uses repo default base branch)
+/create-pr
+
+# Target specific base branch
+/create-pr --base develop
+
+# Create as draft PR
+/create-pr --draft
+
+# Specify base branch and draft
+/create-pr -b develop -d
+```
+
+After pushing the branch, the PR will open in your browser pre-filled with title and body. Add reviewers/labels in the web UI before creating.

hooks/hooks.json

@@ -0,0 +1,31 @@
+{
+  "description": "Safety and quality hooks for Claude Code Arsenal",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "description": "Security validation: Protects sensitive files from modification",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run --directory ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/hooks/security/file_protection.py",
+            "description": "Prevents modification of sensitive files (.env, keys, production configs)",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "description": "Quality validation: Pre-commit checks",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run --directory ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/hooks/quality/pre_commit_validate.py",
+            "description": "Runs linting and tests before git commits",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}

plugin.lock.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:mgiovani/cc-arsenal:",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "5d5ecdc21709000c0332f874ad3b8eef834263b7",
+    "treeHash": "33648f176b67b37a61188299114acec542d9ee74e7a4959e270c729bf6ed0140",
+    "generatedAt": "2025-11-28T10:27:04.940762Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "cc-arsenal",
+    "description": "Security-focused AI agents, quality automation commands, and safety hooks for Claude Code",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "ddf33d5b6ab50793ef24d15745a83a54fcfce7e9043d9de4da1f49c8f38fc0ba"
+      },
+      {
+        "path": "hooks/hooks.json",
+        "sha256": "828e6ee32c5f8d275550de13f00df0a93cd8fc60091112d050e549b39fb1fca3"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "d9039a7b93fafcafae8b805a480feff8694e3cef99c6af73882eecde5e7c6cfc"
+      },
+      {
+        "path": "commands/docs/rfc.md",
+        "sha256": "97754134871582e988b0d9924a517dca523c6c3e6e18b315f01a41ea8f782fcc"
+      },
+      {
+        "path": "commands/docs/init.md",
+        "sha256": "3dd5d7358ad6c93ed8c1f6e607b248055f535a233ab23709ee15cea0c7d61e4d"
+      },
+      {
+        "path": "commands/docs/check.md",
+        "sha256": "bd057acb75cac4619dff8f22ef43d50a84fc1df7ae192c7962f2d919617f86ae"
+      },
+      {
+        "path": "commands/docs/diagram.md",
+        "sha256": "b0ae211c5ce9865a3e530182b1e3293970b83b7498951b7e174acedd18fa033f"
+      },
+      {
+        "path": "commands/docs/update.md",
+        "sha256": "ed9457156fce74918634ba7f9bca8b1dce7cb7c1089733de72fd4ee9f9c93ced"
+      },
+      {
+        "path": "commands/docs/adr.md",
+        "sha256": "8fac72014424db0c9d92a062c0949aaa82bd838cb0863a472d78b5aecdcb5a10"
+      },
+      {
+        "path": "commands/git/create-pr.md",
+        "sha256": "47902354da8fb75ca53d0277158ce99f95efd31970a002d185ab89d163df11d4"
+      },
+      {
+        "path": "commands/git/commit.md",
+        "sha256": "4d08668baf9e58f0020e7a7ad736aa8a1ab66c6448f508db566e938be7b900f6"
+      },
+      {
+        "path": "skills/skill-creator/SKILL.md",
+        "sha256": "8c0ce23bb87be91f5b0853c2e9815617c3858b63acdddfe5da47d2c2d3a60816"
+      },
+      {
+        "path": "skills/skill-creator/LICENSE.txt",
+        "sha256": "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4"
+      },
+      {
+        "path": "skills/skill-creator/scripts/init_skill.py",
+        "sha256": "cad1af5073c5bf4d6c78e71feb776372d1d1112fcb32a38eae3960cac6482dac"
+      },
+      {
+        "path": "skills/skill-creator/scripts/package_skill.py",
+        "sha256": "306a2725b0840809058d7c56adde3b1757dca5a45008f3298e251ac3529fe386"
+      },
+      {
+        "path": "skills/skill-creator/scripts/quick_validate.py",
+        "sha256": "66920614c2d952b650e979ee5c6840e696aa043dbcc61c9702d0cb565d6bb25c"
+      },
+      {
+        "path": "skills/jira-cli/SKILL.md",
+        "sha256": "ca18cd6c284b8a489f8c432b80deec55f953a897646f5a7e22fed653358fb7e6"
+      },
+      {
+        "path": "skills/jira-cli/references/workflows.md",
+        "sha256": "f7f0e5b4f49d1cebc5a1d4e0a46d85658d76b9b0994579f8e63b165bb4a13717"
+      },
+      {
+        "path": "skills/jira-cli/references/commands.md",
+        "sha256": "4ae9eb25ca8376f06ee6936e56ce03e27ad27a4ac2a84c2d24f52cb0970b3999"
+      },
+      {
+        "path": "skills/jira-cli/references/scripting.md",
+        "sha256": "94623d999fc6a5eab71dbc70a96142ac9a339d44bd13fef68dba26583c178572"
+      }
+    ],
+    "dirSha256": "33648f176b67b37a61188299114acec542d9ee74e7a4959e270c729bf6ed0140"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/jira-cli/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: jira-cli
+description: Interactive command-line tool for Atlassian Jira. This skill should be used when users want to interact with Jira issues, epics, sprints, or when they mention Jira workflows, issue management, or need help with jira-cli commands and workflows.
+---
+
+# Jira CLI
+
+Interactive command-line tool for Atlassian Jira that minimizes reliance on the web interface while maintaining essential functionality for daily Jira operations.
+
+## Overview
+
+JiraCLI (`jira-cli`) is a command line tool for managing Jira issues, epics, and sprints. Supports both Jira Cloud and on-premise installations with multiple authentication methods.
+
+**For AI use, always add `--plain` flag to get plain text output suitable for parsing.**
+
+## When to Use This Skill
+
+Use this skill when:
+- Managing Jira issues from the command line
+- Creating, editing, or viewing Jira tickets
+- Working with epics and sprints
+- Automating Jira workflows
+- Users mention "jira", "ticket", "issue", "epic", or "sprint"
+- Writing scripts for Jira automation
+
+## Essential Commands
+
+```bash
+# List recent issues (always use --plain for AI)
+jira issue list --plain
+
+# View issue details
+jira issue view ISSUE-1 --plain
+
+# Create an issue
+jira issue create -tBug -s"Bug title" -yHigh -b"Description"
+
+# Assign issue to yourself
+jira issue assign ISSUE-1 $(jira me)
+
+# Move issue to "In Progress"
+jira issue move ISSUE-1 "In Progress"
+
+# Add comment
+jira issue comment add ISSUE-1 --comment "My comment"
+
+# Add worklog
+jira issue worklog add ISSUE-1 "2h" --comment "Implementation work"
+```
+
+## How to Use This Skill
+
+**For detailed command reference and examples, load the appropriate reference file:**
+
+### 1. Comprehensive Commands Reference
+
+**Load:** [references/commands.md](./references/commands.md)
+
+Use this file when you need:
+- Detailed command syntax and options
+- All available flags and parameters
+- Issue management operations (list, create, edit, assign, move, view, link, clone, delete)
+- Epic management (list, create, add/remove issues)
+- Sprint management (list, add issues)
+- Release management
+- Output format options
+- Non-interactive command patterns
+
+### 2. Common Workflow Examples
+
+**Load:** [references/workflows.md](./references/workflows.md)
+
+Use this file when you need:
+- Daily standup preparation workflows
+- Sprint planning commands
+- Code review workflow integration
+- Bug triage procedures
+- Team collaboration patterns
+- Best practices for different scenarios
+
+### 3. Scripting and Automation
+
+**Load:** [references/scripting.md](./references/scripting.md)
+
+Use this file when you need:
+- Bash automation scripts
+- Data extraction and reporting
+- Integration with CI/CD pipelines
+- Metrics and analytics examples
+- Bulk operations
+
+## Quick Reference
+
+### Powerful List Filters
+
+```bash
+# Combine flags for precise queries (always add --plain)
+jira issue list --plain -a$(jira me) -yHigh -s"To Do" --created -7d -lbackend
+
+# Use tilde (~) as NOT operator
+jira issue list --plain -s~Done --created-before -24w
+
+# Filter by multiple criteria
+jira issue list --plain -yHigh,Critical -s"In Progress" -lbug
+
+# List issues I'm watching
+jira issue list --plain -w
+
+# List issues assigned to no one created this week
+jira issue list --plain -ax --created week
+
+# List issues created within an hour
+jira issue list --plain --created -1h
+
+# List issues from history (recently viewed)
+jira issue list --plain --history
+```
+
+### Sprint Management
+
+```bash
+# List current active sprint issues
+jira sprint list --plain --current
+
+# List current sprint issues assigned to me
+jira sprint list --plain --current -a$(jira me)
+
+# List previous sprint issues
+jira sprint list --plain --prev
+
+# List next planned sprint issues
+jira sprint list --plain --next
+
+# List future and active sprints
+jira sprint list --plain --state future,active
+
+# List issues in a specific sprint (use sprint ID)
+jira sprint list --plain SPRINT_ID
+
+# Add issues to a sprint
+jira sprint add SPRINT_ID ISSUE-1 ISSUE-2
+```
+
+### Epic Management
+
+```bash
+# List epics in table view
+jira epic list --plain --table
+
+# List issues in an epic
+jira epic list --plain KEY-1
+
+# List unassigned high priority issues in an epic
+jira epic list --plain KEY-1 -ax -yHigh
+
+# Add issues to an epic (up to 50 at once)
+jira epic add EPIC-KEY ISSUE-1 ISSUE-2
+
+# Remove issues from an epic
+jira epic remove ISSUE-1 ISSUE-2
+```
+
+### Useful Scripts
+
+```bash
+# Get ticket count per sprint
+sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
+echo "${sprints}" | while read -r id name; do
+  count=$(jira sprint list "${id}" --plain --no-headers 2>/dev/null | wc -l)
+  printf "%s: %d\n" "${name}" "${count}"
+done
+
+# List tickets created today
+jira issue list --plain --created -1d
+
+# List high priority bugs assigned to me
+jira issue list --plain -a$(jira me) -tBug -yHigh
+
+# Get issues by date range
+jira issue list --plain --created week
+jira issue list --plain --created month
+jira issue list --plain --created -7d
+jira issue list --plain --updated -30m
+```
+
+## Resources
+
+- **GitHub**: https://github.com/ankitpokhrel/jira-cli
+- **Installation Guide**: https://github.com/ankitpokhrel/jira-cli/wiki/Installation
+- **FAQs**: https://github.com/ankitpokhrel/jira-cli/discussions/categories/faqs

skills/jira-cli/references/commands.md

@@ -0,0 +1,464 @@
+# Jira CLI - Comprehensive Command Reference
+
+This file contains detailed command syntax, options, and examples for all jira-cli operations.
+
+## Issue Management
+
+### Listing Issues
+
+Use powerful filters to find exactly what you need:
+
+```bash
+# Basic listing
+jira issue list                          # Recent issues
+jira issue list "Feature Request"        # Search by specific text
+jira issue list --created -7d            # Last 7 days
+jira issue list -s"To Do"                # Specific status
+jira issue list -yHigh                   # High priority
+
+# Personal queries
+jira issue list -a$(jira me)             # Assigned to me
+jira issue list -r$(jira me)             # Reported by me
+jira issue list -w                       # Issues I'm watching
+
+# Filtering by fields
+jira issue list -lbackend                # With label
+jira issue list -CBackend                # With component
+jira issue list -tBug                    # Bug type
+jira issue list -R"Won't do"             # With resolution
+
+# Combined filters (high priority, In Progress, created this month, with labels)
+jira issue list -yHigh -s"In Progress" --created month -lbackend -l"high-prio"
+
+# Time-based queries
+jira issue list --created -1h            # Created in last hour
+jira issue list --updated -30m           # Updated in last 30 minutes
+jira issue list --created week           # Created this week
+jira issue list --created month          # Created this month
+jira issue list --created-before -24w    # Created before 24 weeks ago
+
+# Advanced queries
+jira issue list -a"User A" -r"User B"    # Assigned to A, reported by B
+jira issue list -ax                      # Unassigned issues
+jira issue list -a~x                     # Assigned to anyone
+jira issue list -s~Done                  # Status NOT done (~ is NOT)
+jira issue list -s~Done --created-before -24w -a~x  # Complex NOT query
+
+# Special queries
+jira issue list --history                # Recently viewed by you
+jira issue list -r$(jira me) --reverse  # First issue you ever reported
+jira issue list -a$(jira me) -tBug -sDone -rFixed --reverse  # First bug you fixed
+
+# Project-specific
+jira issue list -pXYZ                    # In project XYZ
+jira issue list -w -pXYZ                 # Watching in project XYZ
+
+# Sorting and ordering
+jira issue list --order-by rank --reverse     # By rank (same as UI)
+jira issue list --order-by created           # By creation date
+jira issue list --order-by updated           # By update date
+
+# Output formats
+jira issue list --plain                  # Plain text
+jira issue list --csv                    # CSV format
+jira issue list --raw                    # Raw JSON
+jira issue list --columns key,summary,status,assignee  # Custom columns
+jira issue list --plain --no-headers     # No headers (for parsing)
+
+# Raw JQL
+jira issue list -q "summary ~ cli"       # Execute JQL in project context
+```
+
+### Creating Issues
+
+```bash
+# Interactive mode
+jira issue create
+
+# Non-interactive with all parameters
+jira issue create -tBug -s"Bug title" -yHigh -lbug -lurgent -b"Description" --no-input
+
+# Create with specific fields
+jira issue create -tStory -s"Story title" -yMedium -lfeature
+jira issue create -tTask -s"Task" -a"John Doe"  -CBackend
+jira issue create -tBug -s"Critical bug" -yHighest --fix-version v2.0
+
+# Attach to epic during creation
+jira issue create -tStory -s"Story title" -PEPIC-42
+
+# Using templates for description
+jira issue create --template /path/to/template.md
+jira issue create --template -                    # From stdin
+
+# Pipe description from stdin
+echo "Description from pipeline" | jira issue create -s"Summary" -tTask
+
+# With custom fields
+jira issue create --custom field1=value1 --custom field2=value2
+```
+
+### Editing Issues
+
+```bash
+# Interactive edit
+jira issue edit ISSUE-1
+
+# Update specific fields
+jira issue edit ISSUE-1 -s"New summary"
+jira issue edit ISSUE-1 -yHigh
+jira issue edit ISSUE-1 -b"New description"
+
+# Update multiple fields at once
+jira issue edit ISSUE-1 -s"New summary" -yHigh -lurgent --no-input
+
+# Add and remove labels/components
+jira issue edit ISSUE-1 --label new-label
+jira issue edit ISSUE-1 --label -old-label --label new-label
+jira issue edit ISSUE-1 --component -FE --component BE
+
+# Update fix version
+jira issue edit ISSUE-1 --fix-version v2.0
+jira issue edit ISSUE-1 --fix-version -v1.0 --fix-version v2.0
+```
+
+### Assigning Issues
+
+```bash
+# Interactive assign
+jira issue assign
+
+# Assign to specific user
+jira issue assign ISSUE-1 "Jon Doe"
+
+# Assign to self
+jira issue assign ISSUE-1 $(jira me)
+
+# Assign based on keyword (prompts if multiple matches)
+jira issue assign ISSUE-1 john
+
+# Assign to default assignee
+jira issue assign ISSUE-1 default
+
+# Unassign
+jira issue assign ISSUE-1 x
+```
+
+### Moving/Transitioning Issues
+
+```bash
+# Interactive transition
+jira issue move
+
+# Move to specific status
+jira issue move ISSUE-1 "In Progress"
+jira issue move ISSUE-1 Done
+
+# Move with comment
+jira issue move ISSUE-1 "In Progress" --comment "Started working on it"
+
+# Set resolution and assignee while moving
+jira issue move ISSUE-1 Done -RFixed
+jira issue move ISSUE-1 Done -RFixed -a$(jira me)
+```
+
+### Viewing Issues
+
+```bash
+# View issue in terminal
+jira issue view ISSUE-1
+
+# View with recent comments
+jira issue view ISSUE-1 --comments 5
+jira issue view ISSUE-1 --comments 10
+```
+
+### Linking Issues
+
+```bash
+# Interactive linking
+jira issue link
+
+# Link with relationship type
+jira issue link ISSUE-1 ISSUE-2 Blocks
+jira issue link ISSUE-1 ISSUE-2 "is blocked by"
+jira issue link ISSUE-1 ISSUE-2 Duplicates
+jira issue link ISSUE-1 ISSUE-2 Relates
+
+# Add remote web link
+jira issue link remote ISSUE-1 https://example.com "Example text"
+jira issue link remote ISSUE-1 https://github.com/org/repo/pull/123 "PR #123"
+
+# Unlink issues
+jira issue unlink ISSUE-1 ISSUE-2
+```
+
+### Cloning Issues
+
+```bash
+# Clone an issue
+jira issue clone ISSUE-1
+
+# Clone with modifications
+jira issue clone ISSUE-1 -s"Modified summary"
+jira issue clone ISSUE-1 -s"New title" -yHigh -a$(jira me)
+
+# Clone and replace text in summary/description
+jira issue clone ISSUE-1 -H"old text:new text"
+jira issue clone ISSUE-1 -H"2024:2025"
+```
+
+### Deleting Issues
+
+```bash
+# Interactive delete
+jira issue delete
+
+# Delete specific issue
+jira issue delete ISSUE-1
+
+# Delete with all subtasks
+jira issue delete ISSUE-1 --cascade
+```
+
+### Comments
+
+```bash
+# Add comment interactively
+jira issue comment add
+
+# Add comment with text
+jira issue comment add ISSUE-1 "My comment text"
+
+# Add internal comment (visible only to team)
+jira issue comment add ISSUE-1 "Internal note" --internal
+
+# Add comment from template
+jira issue comment add ISSUE-1 --template /path/to/comment.md
+jira issue comment add ISSUE-1 --template -
+
+# Pipe comment from stdin
+echo "Comment from pipeline" | jira issue comment add ISSUE-1
+```
+
+### Worklog (Time Tracking)
+
+```bash
+# Add worklog interactively
+jira issue worklog add
+
+# Add worklog with time
+jira issue worklog add ISSUE-1 "2h 30m" --no-input
+jira issue worklog add ISSUE-1 "1d" --no-input
+jira issue worklog add ISSUE-1 "30m" --no-input
+
+# Add worklog with comment
+jira issue worklog add ISSUE-1 "2h" --comment "Implementation work" --no-input
+jira issue worklog add ISSUE-1 "1h 15m" --comment "Code review" --no-input
+```
+
+## Epic Management
+
+### Listing Epics
+
+```bash
+# List all epics (explorer view)
+jira epic list
+
+# List epics (table view)
+jira epic list --table
+
+# List epics with filters (same filters as issue list)
+jira epic list -r$(jira me)              # Reported by me
+jira epic list -sOpen                     # Open epics
+jira epic list -yHigh                     # High priority
+jira epic list -r$(jira me) -sOpen -yHigh  # Combined filters
+
+# List issues in an epic
+jira epic list EPIC-1
+
+# List epic issues with filters
+jira epic list EPIC-1 -ax                # Unassigned issues in epic
+jira epic list EPIC-1 -yHigh             # High priority issues in epic
+jira epic list EPIC-1 -a$(jira me)      # My issues in epic
+
+# Order epic issues by rank
+jira epic list EPIC-1 --order-by rank --reverse
+```
+
+### Creating Epics
+
+```bash
+# Interactive
+jira epic create
+
+# With parameters
+jira epic create -n"Epic name" -s"Epic summary"
+jira epic create -n"Q1 Features" -s"Q1 Feature Development" -yHigh -lfeature -b"Epic description"
+```
+
+### Managing Epic Issues
+
+```bash
+# Add issues to epic (interactive)
+jira epic add
+
+# Add issues to epic (up to 50 at once)
+jira epic add EPIC-1 ISSUE-1 ISSUE-2 ISSUE-3
+
+# Remove issues from epic (interactive)
+jira epic remove
+
+# Remove issues from epic (up to 50 at once)
+jira epic remove ISSUE-1 ISSUE-2 ISSUE-3
+```
+
+## Sprint Management
+
+### Listing Sprints
+
+```bash
+# List all sprints (explorer view)
+jira sprint list
+
+# List sprints (table view)
+jira sprint list --table
+
+# Current active sprint
+jira sprint list --current
+
+# Current sprint with filters
+jira sprint list --current -a$(jira me)
+jira sprint list --current -yHigh
+jira sprint list --current -a$(jira me) -yHigh -s"In Progress"
+
+# Previous sprint
+jira sprint list --prev
+
+# Next planned sprint
+jira sprint list --next
+
+# Filter by sprint state
+jira sprint list --state active
+jira sprint list --state future
+jira sprint list --state future,active
+jira sprint list --state closed
+
+# Specific sprint (use ID from sprint list)
+jira sprint list SPRINT_ID
+jira sprint list SPRINT_ID -yHigh
+jira sprint list SPRINT_ID -a$(jira me)
+jira sprint list SPRINT_ID -yHigh -a$(jira me) -s"In Progress"
+
+# Order sprint issues by rank
+jira sprint list SPRINT_ID --order-by rank --reverse
+```
+
+### Adding Issues to Sprint
+
+```bash
+# Add issues interactively
+jira sprint add
+
+# Add multiple issues (up to 50 at once)
+jira sprint add SPRINT_ID ISSUE-1 ISSUE-2 ISSUE-3
+```
+
+## Release Management
+
+Interact with releases (project versions). Ensure the [feature is enabled](https://support.atlassian.com/jira-software-cloud/docs/enable-releases-and-versions/) on your instance.
+
+```bash
+# List releases for default project
+jira release list
+
+# List releases for specific project by ID
+jira release list --project 1000
+
+# List releases for specific project by key
+jira release list --project MYPROJ
+```
+
+## Other Commands
+
+### Project and Board Navigation
+
+```bash
+# Open project in browser
+jira open
+
+# Open specific issue in browser
+jira open ISSUE-1
+
+# List all projects you have access to
+jira project list
+
+# List all boards in a project
+jira board list
+```
+
+### User Information
+
+```bash
+# Get your own username (useful in scripts)
+jira me
+```
+
+## Navigation and Interaction
+
+When in interactive UI:
+
+**Movement:**
+- **Arrow keys** or **j,k,h,l** - Navigate through list
+- **g** - Jump to top
+- **G** - Jump to bottom
+- **CTRL+f** - Scroll page down
+- **CTRL+b** - Scroll page up
+
+**Actions:**
+- **v** - View selected issue details
+- **m** - Transition the selected issue
+- **CTRL+r** or **F5** - Refresh the list
+- **ENTER** - Open selected issue in browser
+- **c** - Copy issue URL to clipboard (requires xclip/xsel on Linux)
+- **CTRL+k** - Copy issue key to clipboard
+- **w** or **TAB** - Toggle focus between sidebar and content
+- **q** / **ESC** / **CTRL+c** - Quit
+- **?** - Show help window
+
+## Output Formats and Options
+
+### Format Options
+
+```bash
+# Interactive table (default)
+jira issue list
+
+# Plain text output (for scripts)
+jira issue list --plain
+
+# CSV format (for spreadsheets)
+jira issue list --csv
+
+# Raw JSON (for programmatic parsing)
+jira issue list --raw
+```
+
+### Column Selection
+
+```bash
+# Default columns
+jira issue list
+
+# Custom columns
+jira issue list --columns key,summary,status
+jira issue list --columns key,summary,status,assignee,priority
+jira issue list --columns created,updated,reporter
+
+# Without headers (for parsing)
+jira issue list --plain --no-headers
+jira issue list --csv --no-headers
+```
+
+### Pagination
+
+jira-cli handles pagination automatically. For very large result sets, the tool will fetch additional pages as needed.

skills/jira-cli/references/scripting.md

@@ -0,0 +1,457 @@
+# Jira CLI - Scripting and Automation
+
+This file contains examples for automating Jira operations with scripts and integrating with CI/CD pipelines.
+
+## Bash Scripting Examples
+
+### Tickets Created Per Day This Month
+
+```bash
+#!/usr/bin/env bash
+# Generate report of tickets created per day in current month
+
+tickets=$(jira issue list --created month --plain --columns created --no-headers | \
+  awk '{print $2}' | awk -F'-' '{print $3}' | sort -n | uniq -c)
+
+echo "${tickets}" | while IFS=$'\t' read -r line; do
+  day=$(echo "${line}" | awk '{print $2}')
+  count=$(echo "${line}" | awk '{print $1}')
+  printf "Day #%s: %s tickets\n" "${day}" "${count}"
+done
+```
+
+### Number of Tickets Per Sprint
+
+```bash
+#!/usr/bin/env bash
+# Count tickets in each sprint
+
+sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
+
+echo "${sprints}" | while IFS=$'\t' read -r id name; do
+  count=$(jira sprint list "${id}" --plain --no-headers 2>/dev/null | wc -l)
+  printf "%10s: %3d tickets\n" "${name}" $((count))
+done
+```
+
+### Number of Unique Assignees Per Sprint
+
+```bash
+#!/usr/bin/env bash
+# Count unique assignees in each sprint
+
+sprints=$(jira sprint list --table --plain --columns id,name --no-headers)
+
+echo "${sprints}" | while IFS=$'\t' read -r id name; do
+  count=$(jira sprint list "${id}" --plain --columns assignee --no-headers 2>/dev/null | \
+    awk '{print $2}' | awk NF | sort -n | uniq | wc -l)
+  printf "%10s: %3d people\n" "${name}" $((count))
+done
+```
+
+### Daily Standup Report
+
+```bash
+#!/usr/bin/env bash
+# Generate daily standup report
+
+echo "=== Daily Standup Report ==="
+echo ""
+
+echo "Yesterday's work (updated in last 24h):"
+jira issue list -a$(jira me) --updated -1d --plain --columns key,summary
+
+echo ""
+echo "Currently working on:"
+jira issue list -a$(jira me) -s"In Progress" --plain --columns key,summary
+
+echo ""
+echo "Closed this week:"
+jira issue list -a$(jira me) -sDone --updated week --plain --columns key,summary
+```
+
+### Sprint Report Generator
+
+```bash
+#!/usr/bin/env bash
+# Generate sprint summary report
+
+SPRINT_ID=$1
+
+if [ -z "$SPRINT_ID" ]; then
+  echo "Usage: $0 <sprint-id>"
+  exit 1
+fi
+
+echo "=== Sprint Report for Sprint $SPRINT_ID ==="
+echo ""
+
+total=$(jira sprint list "$SPRINT_ID" --plain --no-headers | wc -l)
+done_count=$(jira sprint list "$SPRINT_ID" -sDone --plain --no-headers | wc -l)
+in_progress=$(jira sprint list "$SPRINT_ID" -s"In Progress" --plain --no-headers | wc -l)
+todo=$(jira sprint list "$SPRINT_ID" -s"To Do" --plain --no-headers | wc -l)
+
+echo "Total tickets: $total"
+echo "Done: $done_count"
+echo "In Progress: $in_progress"
+echo "To Do: $todo"
+echo ""
+
+completion_rate=$(echo "scale=2; ($done_count / $total) * 100" | bc)
+echo "Completion rate: ${completion_rate}%"
+```
+
+### Bulk Issue Assignment
+
+```bash
+#!/usr/bin/env bash
+# Assign unassigned high priority tickets to team members
+
+# Get list of unassigned high priority tickets
+issues=$(jira issue list -ax -yHigh -s"To Do" --plain --columns key --no-headers)
+
+# Team members
+team=("Alice" "Bob" "Charlie")
+team_size=${#team[@]}
+index=0
+
+# Assign in round-robin fashion
+for issue in $issues; do
+  assignee="${team[$index]}"
+  echo "Assigning $issue to $assignee"
+  jira issue assign "$issue" "$assignee"
+  index=$(( (index + 1) % team_size ))
+done
+```
+
+### Auto-Label Based on Summary
+
+```bash
+#!/usr/bin/env bash
+# Auto-label issues based on keywords in summary
+
+# Get issues without labels
+issues=$(jira issue list --plain --columns key,summary --no-headers)
+
+echo "$issues" | while IFS=$'\t' read -r key summary; do
+  # Check for keywords and add labels
+  if echo "$summary" | grep -qi "bug\|error\|crash"; then
+    echo "Adding 'bug' label to $key"
+    jira issue edit "$key" --label bug
+  fi
+
+  if echo "$summary" | grep -qi "feature\|enhancement"; then
+    echo "Adding 'enhancement' label to $key"
+    jira issue edit "$key" --label enhancement
+  fi
+
+  if echo "$summary" | grep -qi "urgent\|critical\|blocker"; then
+    echo "Adding 'urgent' label to $key"
+    jira issue edit "$key" --label urgent
+  fi
+done
+```
+
+### Export Issues to CSV
+
+```bash
+#!/usr/bin/env bash
+# Export filtered issues to CSV file
+
+OUTPUT_FILE="issues_$(date +%Y%m%d).csv"
+
+# Export with custom columns
+jira issue list \
+  --created month \
+  --csv \
+  --columns key,type,status,priority,assignee,summary,created \
+  > "$OUTPUT_FILE"
+
+echo "Exported to $OUTPUT_FILE"
+```
+
+### Monitor High Priority Issues
+
+```bash
+#!/usr/bin/env bash
+# Monitor and alert on high priority unassigned issues
+
+THRESHOLD=5
+
+count=$(jira issue list -ax -yHigh -s~Done --plain --no-headers | wc -l)
+
+if [ "$count" -gt "$THRESHOLD" ]; then
+  echo "⚠️  Alert: $count high priority unassigned issues (threshold: $THRESHOLD)"
+  jira issue list -ax -yHigh -s~Done --plain --columns key,summary
+
+  # Could send to Slack, email, etc.
+  # slack-cli send "#team-alerts" "High priority issues need attention: $count tickets"
+else
+  echo "✅ OK: $count high priority unassigned issues"
+fi
+```
+
+## CI/CD Integration
+
+### GitHub Actions - Create Jira Issue on PR
+
+```yaml
+name: Create Jira Issue
+on:
+  pull_request:
+    types: [opened]
+
+jobs:
+  create-jira:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install jira-cli
+        run: |
+          wget https://github.com/ankitpokhrel/jira-cli/releases/latest/download/jira_linux_amd64.tar.gz
+          tar -xf jira_linux_amd64.tar.gz
+          sudo mv jira /usr/local/bin/
+
+      - name: Create Jira Issue
+        env:
+          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+          JIRA_SERVER: ${{ secrets.JIRA_SERVER }}
+          JIRA_PROJECT: ${{ secrets.JIRA_PROJECT }}
+        run: |
+          jira issue create \
+            -tTask \
+            -s"Review PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }}" \
+            -b"${{ github.event.pull_request.html_url }}" \
+            --no-input
+```
+
+### GitLab CI - Update Jira on Deploy
+
+```yaml
+update_jira:
+  stage: deploy
+  script:
+    - |
+      # Extract Jira keys from commit messages
+      JIRA_KEYS=$(git log --format=%B -n 10 | grep -oE '[A-Z]+-[0-9]+' | sort -u)
+
+      for KEY in $JIRA_KEYS; do
+        echo "Updating $KEY to Done"
+        jira issue move "$KEY" Done -RDeployed --comment "Deployed to production"
+      done
+  only:
+    - main
+```
+
+### Jenkins Pipeline - Sprint Metrics
+
+```groovy
+pipeline {
+    agent any
+    triggers {
+        cron('0 9 * * 1')  // Every Monday at 9 AM
+    }
+    stages {
+        stage('Generate Sprint Report') {
+            steps {
+                script {
+                    sh '''
+                        # Get current sprint
+                        SPRINT_ID=$(jira sprint list --current --table --plain --columns id --no-headers)
+
+                        # Generate metrics
+                        echo "Sprint Metrics Report" > sprint_report.txt
+                        echo "===================" >> sprint_report.txt
+
+                        total=$(jira sprint list $SPRINT_ID --plain --no-headers | wc -l)
+                        done=$(jira sprint list $SPRINT_ID -sDone --plain --no-headers | wc -l)
+
+                        echo "Total: $total" >> sprint_report.txt
+                        echo "Done: $done" >> sprint_report.txt
+
+                        # Send to team
+                        cat sprint_report.txt
+                    '''
+                }
+            }
+        }
+    }
+}
+```
+
+## Data Analysis
+
+### Export Data for Analysis
+
+```bash
+#!/usr/bin/env bash
+# Export comprehensive data for analysis
+
+# Create timestamped directory
+DIR="jira_export_$(date +%Y%m%d_%H%M%S)"
+mkdir -p "$DIR"
+
+# Export different views
+echo "Exporting all open issues..."
+jira issue list -s~Done --csv > "$DIR/open_issues.csv"
+
+echo "Exporting completed this month..."
+jira issue list -sDone --updated month --csv > "$DIR/completed_month.csv"
+
+echo "Exporting by assignee..."
+for user in $(jira issue list --plain --columns assignee --no-headers | sort -u); do
+  jira issue list -a"$user" --csv > "$DIR/assignee_${user// /_}.csv"
+done
+
+echo "Export complete in $DIR/"
+```
+
+### Calculate Team Velocity
+
+```bash
+#!/usr/bin/env bash
+# Calculate team velocity over last N sprints
+
+SPRINT_COUNT=5
+
+echo "=== Team Velocity (last $SPRINT_COUNT sprints) ==="
+echo ""
+
+sprints=$(jira sprint list --state closed --table --plain --columns id,name --no-headers | head -$SPRINT_COUNT)
+
+total_points=0
+sprint_count=0
+
+echo "$sprints" | while IFS=$'\t' read -r id name; do
+  # Assuming story points in summary or custom field
+  completed=$(jira sprint list "$id" -sDone --plain --no-headers | wc -l)
+  echo "$name: $completed stories"
+
+  total_points=$((total_points + completed))
+  sprint_count=$((sprint_count + 1))
+done
+
+# Calculate average
+if [ $sprint_count -gt 0 ]; then
+  avg=$(echo "scale=2; $total_points / $sprint_count" | bc)
+  echo ""
+  echo "Average velocity: $avg stories per sprint"
+fi
+```
+
+## Automation Helpers
+
+### Auto-Transition Based on PR Status
+
+```bash
+#!/usr/bin/env bash
+# Auto-transition Jira issues based on PR status
+
+# Get list of open PRs from GitHub
+# (requires gh CLI)
+prs=$(gh pr list --json number,title --jq '.[] | "\(.number)|\(.title)"')
+
+echo "$prs" | while IFS='|' read -r number title; do
+  # Extract Jira key from PR title
+  jira_key=$(echo "$title" | grep -oE '[A-Z]+-[0-9]+' | head -1)
+
+  if [ -n "$jira_key" ]; then
+    # Check current status
+    status=$(jira issue view "$jira_key" --plain | grep "Status:" | awk '{print $2}')
+
+    # Move to In Review if not already
+    if [ "$status" != "Review" ]; then
+      echo "Moving $jira_key to In Review (PR #$number)"
+      jira issue move "$jira_key" "In Review"
+      jira issue link remote "$jira_key" "https://github.com/org/repo/pull/$number" "PR #$number"
+    fi
+  fi
+done
+```
+
+### Stale Issue Cleanup
+
+```bash
+#!/usr/bin/env bash
+# Find and handle stale issues
+
+# Find issues not updated in 3 months
+stale=$(jira issue list --updated-before -12w -s"To Do" --plain --columns key,summary --no-headers)
+
+echo "$stale" | while IFS=$'\t' read -r key summary; do
+  echo "Stale issue found: $key - $summary"
+
+  # Add comment asking for update
+  jira issue comment add "$key" "This issue hasn't been updated in 3 months. Is it still relevant?"
+
+  # Add stale label
+  jira issue edit "$key" --label stale
+
+  # Optionally: move to backlog or close
+  # jira issue move "$key" "Backlog"
+done
+```
+
+## Best Practices for Scripts
+
+### Error Handling
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail  # Exit on error, undefined vars, pipe failures
+
+# Check if jira-cli is available
+if ! command -v jira &> /dev/null; then
+  echo "Error: jira-cli not found. Please install it first."
+  exit 1
+fi
+
+# Check for required environment variables
+if [ -z "${JIRA_API_TOKEN:-}" ]; then
+  echo "Error: JIRA_API_TOKEN not set"
+  exit 1
+fi
+
+# Wrap jira commands with error handling
+if ! jira issue list -a$(jira me) 2>&1; then
+  echo "Error: Failed to fetch issues"
+  exit 1
+fi
+```
+
+### Logging and Debugging
+
+```bash
+#!/usr/bin/env bash
+
+# Enable debug mode
+DEBUG=${DEBUG:-false}
+
+debug() {
+  if [ "$DEBUG" = "true" ]; then
+    echo "[DEBUG] $*" >&2
+  fi
+}
+
+debug "Starting script..."
+debug "Fetching issues for user: $(jira me)"
+
+issues=$(jira issue list -a$(jira me) --plain --columns key --no-headers)
+debug "Found $(echo "$issues" | wc -l) issues"
+```
+
+### Rate Limiting
+
+```bash
+#!/usr/bin/env bash
+
+# Process issues with rate limiting
+issues=$(jira issue list --plain --columns key --no-headers)
+
+for issue in $issues; do
+  echo "Processing $issue"
+  jira issue view "$issue" > /dev/null
+
+  # Rate limit: 1 request per second
+  sleep 1
+done
+```

skills/jira-cli/references/workflows.md

@@ -0,0 +1,290 @@
+# Jira CLI - Common Workflows
+
+This file contains practical workflow examples for common Jira use cases and team collaboration scenarios.
+
+## Daily Standup Preparation
+
+Get quick answers for your daily standup:
+
+```bash
+# What did I work on yesterday?
+jira issue list -a$(jira me) --updated -1d
+
+# What am I working on today?
+jira issue list -a$(jira me) -s"In Progress"
+
+# What tickets did I close this week?
+jira issue list -a$(jira me) -sDone --updated week
+
+# Any blockers? (high priority issues assigned to me)
+jira issue list -a$(jira me) -yHigh -s~Done
+```
+
+## Sprint Planning
+
+Prepare for and manage sprint planning:
+
+```bash
+# High priority unassigned tickets (need assignment)
+jira issue list -ax -yHigh
+
+# Backlog items ready for sprint (ordered by rank like UI)
+jira issue list -s"Ready for Dev" --order-by rank --reverse
+
+# Current sprint progress
+jira sprint list --current
+
+# Current sprint with my tasks only
+jira sprint list --current -a$(jira me)
+
+# See what's planned for next sprint
+jira sprint list --next
+
+# Check sprint capacity (how many issues)
+jira sprint list SPRINT_ID --plain --no-headers | wc -l
+```
+
+## Code Review Workflow
+
+Integrate Jira with your code review process:
+
+```bash
+# 1. Create ticket for review
+jira issue create -tTask -s"Code review: Feature X"
+
+# 2. Link to related PR
+jira issue link remote ISSUE-1 https://github.com/org/repo/pull/123 "PR #123"
+
+# 3. Move to review status
+jira issue move ISSUE-1 "In Review"
+
+# 4. Add review comments
+jira issue comment add ISSUE-1 "LGTM! Approved changes."
+
+# 5. Close the ticket
+jira issue move ISSUE-1 Done -RFixed
+```
+
+## Bug Triage
+
+Efficient bug triage workflow:
+
+```bash
+# List new bugs from last week
+jira issue list -tBug -sOpen --created -7d
+
+# List critical/high priority bugs
+jira issue list -tBug -yHighest,High -s~Done
+
+# Assign high priority bug to team lead
+jira issue assign BUG-123 "Team Lead"
+
+# Add triage notes
+jira issue comment add BUG-123 "Investigating root cause. Checking logs."
+
+# Update priority and labels
+jira issue edit BUG-123 -yHigh -lproduction -lurgent
+
+# Link to related issues
+jira issue link BUG-123 BUG-100 "is caused by"
+```
+
+## Epic Management Workflow
+
+Working with epics effectively:
+
+```bash
+# Create a new epic for quarterly goals
+jira epic create -n"Q1 2025 Goals" -s"Q1 Goals" -yHigh
+
+# List open epics to see what's in progress
+jira epic list -sOpen
+
+# View all tasks in a specific epic
+jira epic list EPIC-42
+
+# Add new stories to the epic
+jira issue create -tStory -s"User authentication" -PEPIC-42
+jira epic add EPIC-42 STORY-100 STORY-101
+
+# Check epic progress (how many done vs total)
+jira epic list EPIC-42 -sDone --plain --no-headers | wc -l
+jira epic list EPIC-42 --plain --no-headers | wc -l
+
+# Remove completed stories from epic
+jira epic remove STORY-98 STORY-99
+```
+
+## Release Management
+
+Managing releases and versions:
+
+```bash
+# List all releases
+jira release list
+
+# List releases for specific project
+jira release list --project MYPROJECT
+
+# Create issues for a release
+jira issue create -tBug -s"Release blocker" --fix-version v2.0
+
+# Find all issues in a release
+jira issue list --fix-version v2.0
+
+# Find unresolved issues blocking release
+jira issue list --fix-version v2.0 -s~Done
+```
+
+## Team Collaboration
+
+Collaborate effectively with your team:
+
+```bash
+# See what your teammate is working on
+jira issue list -a"John Doe" -s"In Progress"
+
+# Find issues reported by PM for review
+jira issue list -r"Jane PM" -s"To Do" --order-by priority
+
+# Check team's completed work this week
+jira issue list -a~x --updated week -sDone
+
+# Find unassigned high priority work
+jira issue list -ax -yHigh -s"To Do"
+
+# Check who's working on what in current sprint
+jira sprint list --current --plain --columns assignee,key,summary
+```
+
+## Incident Response
+
+Handle production incidents:
+
+```bash
+# Create critical incident ticket
+jira issue create -tBug -s"Production outage: API down" -yHighest -lincident -lproduction --no-input
+
+# Link related issues
+jira issue link INC-1 BUG-789 "is caused by"
+
+# Add status updates
+jira issue comment add INC-1 "Root cause identified. Rolling back deployment."
+
+# Track time spent
+jira issue worklog add INC-1 "2h" --comment "Incident response" --no-input
+
+# Close incident
+jira issue move INC-1 Done -RFixed --comment "Service restored. Post-mortem scheduled."
+```
+
+## Backlog Grooming
+
+Keep your backlog organized:
+
+```bash
+# Find old unassigned tickets (potential cleanup candidates)
+jira issue list -ax --created-before -12w -s"To Do"
+
+# Find tickets with no recent activity
+jira issue list --updated-before -8w -s~Done
+
+# Find tickets missing labels or components
+jira issue list -l~x -C~x
+
+# Update stale tickets in bulk (interactive or scripted)
+for issue in $(jira issue list -ax --created-before -12w --plain --columns key --no-headers); do
+  jira issue edit $issue -s"To Do" --label stale
+done
+```
+
+## Cross-Team Coordination
+
+Working across teams:
+
+```bash
+# Find issues blocked by other teams
+jira issue list -a$(jira me) -lblocked --plain --columns key,summary,status
+
+# Check dependencies in a project
+jira issue list -pOTHERPROJ -a"Dependency Owner"
+
+# See what other teams need from you
+jira issue list -r~$(jira me) -a$(jira me) --plain --columns key,reporter,summary
+
+# Create handoff ticket
+jira issue create -tTask -s"Handoff: Database migration" -CInfra -a"Infrastructure Lead"
+```
+
+## Personal Productivity
+
+Personal task management:
+
+```bash
+# My daily dashboard
+alias jira-today='jira issue list -a$(jira me) -s"In Progress"'
+
+# What I should focus on
+alias jira-priorities='jira issue list -a$(jira me) -yHigh -s~Done --order-by priority'
+
+# What I reported that needs attention
+alias jira-reported='jira issue list -r$(jira me) -s"To Do"'
+
+# Quick add task
+alias jira-task='jira issue create -tTask -a$(jira me)'
+
+# My work this week
+alias jira-week='jira issue list -a$(jira me) --updated week'
+```
+
+## Best Practices
+
+### Efficient Filtering
+
+```bash
+# Combine multiple filters for precision
+jira issue list -a$(jira me) -yHigh -s"In Progress" --created week -lurgent
+
+# Use NOT operator (~) to exclude
+jira issue list -s~Done -s~"In Progress"  # Not done and not in progress
+
+# Time-based queries for recent activity
+jira issue list --updated -2h  # Last 2 hours
+jira issue list --created today  # Created today
+```
+
+### Bulk Operations
+
+```bash
+# Add multiple issues to sprint
+jira sprint add SPRINT_ID $(jira issue list -s"Ready" --plain --columns key --no-headers | head -10 | tr '\n' ' ')
+
+# Batch assign to team members
+for issue in ISSUE-1 ISSUE-2 ISSUE-3; do
+  jira issue assign $issue "Team Member"
+done
+```
+
+### Keyboard Shortcuts in Interactive Mode
+
+Master the interactive UI for speed:
+- Use **j/k** instead of arrows for Vim-like navigation
+- Press **v** to quickly view details without leaving the list
+- Press **m** to transition without navigating to browser
+- Use **c** and **CTRL+k** to quickly copy links/keys for sharing
+
+### Output Formatting for Different Needs
+
+```bash
+# For spreadsheets
+jira issue list --csv > issues.csv
+
+# For scripts
+jira issue list --plain --no-headers --columns key
+
+# For reports
+jira issue list --plain --columns key,status,assignee,summary
+
+# For JSON processing
+jira issue list --raw | jq '.issues[] | {key, summary}'
+```

skills/skill-creator/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

skills/skill-creator/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+license: Complete terms in LICENSE.txt
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Claude's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+**Metadata Quality:** The `name` and `description` in YAML frontmatter determine when Claude will use the skill. Be specific about what the skill does and when to use it. Use the third-person (e.g. "This skill should be used when..." instead of "Use this skill when...").
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
+
+- **When to include**: For documentation that Claude should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Claude (Unlimited*)
+
+*Unlimited because scripts can be executed without reading into context window.
+
+## Skill Creation Process
+
+To create a skill, follow the "Skill Creation Process" in order, skipping steps only if there is a clear reason why they are not applicable.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory>
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Creates example resource directories: `scripts/`, `references/`, and `assets/`
+- Adds example files in each directory that can be customized or deleted
+
+After initialization, customize or remove the generated SKILL.md and example files as needed.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Focus on including information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Also, delete any example files and directories not needed for the skill. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
+
+#### Update SKILL.md
+
+**Writing Style:** Write the entire skill using **imperative/infinitive form** (verb-first instructions), not second person. Use objective, instructional language (e.g., "To accomplish X, do Y" rather than "You should do X" or "If you need to do X"). This maintains consistency and clarity for AI consumption.
+
+To complete SKILL.md, answer the following questions:
+
+1. What is the purpose of the skill, in a few sentences?
+2. When should the skill be used?
+3. In practice, how should Claude use the skill? All reusable skill contents developed above should be referenced so that Claude knows how to use them.
+
+### Step 5: Packaging a Skill
+
+Once the skill is ready, it should be packaged into a distributable zip file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder> ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+   - YAML frontmatter format and required fields
+   - Skill naming conventions and directory structure
+   - Description completeness and quality
+   - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a zip file named after the skill (e.g., `my-skill.zip`) that includes all files and maintains the proper directory structure for distribution.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again

skills/skill-creator/scripts/init_skill.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+    init_skill.py <skill-name> --path <path>
+
+Examples:
+    init_skill.py my-new-skill --path skills/public
+    init_skill.py my-api-helper --path skills/private
+    init_skill.py custom-skill --path /custom/location
+"""
+
+import sys
+from pathlib import Path
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources
+
+This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+    print("This is an example script for {skill_name}")
+    # TODO: Add actual script logic here
+    # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+    main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Claude produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def title_case_skill_name(skill_name):
+    """Convert hyphenated skill name to Title Case for display."""
+    return ' '.join(word.capitalize() for word in skill_name.split('-'))
+
+
+def init_skill(skill_name, path):
+    """
+    Initialize a new skill directory with template SKILL.md.
+
+    Args:
+        skill_name: Name of the skill
+        path: Path where the skill directory should be created
+
+    Returns:
+        Path to created skill directory, or None if error
+    """
+    # Determine skill directory path
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Check if directory already exists
+    if skill_dir.exists():
+        return None
+
+    # Create skill directory
+    try:
+        skill_dir.mkdir(parents=True, exist_ok=False)
+    except Exception:
+        return None
+
+    # Create SKILL.md from template
+    skill_title = title_case_skill_name(skill_name)
+    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)
+
+    skill_md_path = skill_dir / 'SKILL.md'
+    try:
+        skill_md_path.write_text(skill_content)
+    except Exception:
+        return None
+
+    # Create resource directories with example files
+    try:
+        # Create scripts/ directory with example script
+        scripts_dir = skill_dir / 'scripts'
+        scripts_dir.mkdir(exist_ok=True)
+        example_script = scripts_dir / 'example.py'
+        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+        example_script.chmod(0o755)
+
+        # Create references/ directory with example reference doc
+        references_dir = skill_dir / 'references'
+        references_dir.mkdir(exist_ok=True)
+        example_reference = references_dir / 'api_reference.md'
+        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+
+        # Create assets/ directory with example asset placeholder
+        assets_dir = skill_dir / 'assets'
+        assets_dir.mkdir(exist_ok=True)
+        example_asset = assets_dir / 'example_asset.txt'
+        example_asset.write_text(EXAMPLE_ASSET)
+    except Exception:
+        return None
+
+    # Print next steps
+
+    return skill_dir
+
+
+def main() -> None:
+    if len(sys.argv) < 4 or sys.argv[2] != '--path':
+        sys.exit(1)
+
+    skill_name = sys.argv[1]
+    path = sys.argv[3]
+
+    result = init_skill(skill_name, path)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

skills/skill-creator/scripts/package_skill.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable zip file of a skill folder
+
+Usage:
+    python utils/package_skill.py <path/to/skill-folder> [output-directory]
+
+Example:
+    python utils/package_skill.py skills/public/my-skill
+    python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+from quick_validate import validate_skill
+
+
+def package_skill(skill_path, output_dir=None):
+    """
+    Package a skill folder into a zip file.
+
+    Args:
+        skill_path: Path to the skill folder
+        output_dir: Optional output directory for the zip file (defaults to current directory)
+
+    Returns:
+        Path to the created zip file, or None if error
+    """
+    skill_path = Path(skill_path).resolve()
+
+    # Validate skill folder exists
+    if not skill_path.exists():
+        return None
+
+    if not skill_path.is_dir():
+        return None
+
+    # Validate SKILL.md exists
+    skill_md = skill_path / 'SKILL.md'
+    if not skill_md.exists():
+        return None
+
+    # Run validation before packaging
+    valid, message = validate_skill(skill_path)
+    if not valid:
+        return None
+
+    # Determine output location
+    skill_name = skill_path.name
+    if output_dir:
+        output_path = Path(output_dir).resolve()
+        output_path.mkdir(parents=True, exist_ok=True)
+    else:
+        output_path = Path.cwd()
+
+    zip_filename = output_path / f'{skill_name}.zip'
+
+    # Create the zip file
+    try:
+        with zipfile.ZipFile(zip_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # Walk through the skill directory
+            for file_path in skill_path.rglob('*'):
+                if file_path.is_file():
+                    # Calculate the relative path within the zip
+                    arcname = file_path.relative_to(skill_path.parent)
+                    zipf.write(file_path, arcname)
+
+        return zip_filename
+
+    except Exception:
+        return None
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        sys.exit(1)
+
+    skill_path = sys.argv[1]
+    output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+    if output_dir:
+        pass
+
+    result = package_skill(skill_path, output_dir)
+
+    if result:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

skills/skill-creator/scripts/quick_validate.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+def validate_skill(skill_path):
+    """Basic validation of a skill"""
+    skill_path = Path(skill_path)
+
+    # Check SKILL.md exists
+    skill_md = skill_path / 'SKILL.md'
+    if not skill_md.exists():
+        return False, 'SKILL.md not found'
+
+    # Read and validate frontmatter
+    content = skill_md.read_text()
+    if not content.startswith('---'):
+        return False, 'No YAML frontmatter found'
+
+    # Extract frontmatter
+    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not match:
+        return False, 'Invalid frontmatter format'
+
+    frontmatter = match.group(1)
+
+    # Check required fields
+    if 'name:' not in frontmatter:
+        return False, "Missing 'name' in frontmatter"
+    if 'description:' not in frontmatter:
+        return False, "Missing 'description' in frontmatter"
+
+    # Extract name for validation
+    name_match = re.search(r'name:\s*(.+)', frontmatter)
+    if name_match:
+        name = name_match.group(1).strip()
+        # Check naming convention (hyphen-case: lowercase with hyphens)
+        if not re.match(r'^[a-z0-9-]+$', name):
+            return (
+                False,
+                f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)",
+            )
+        if name.startswith('-') or name.endswith('-') or '--' in name:
+            return (
+                False,
+                f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens",
+            )
+
+    # Extract and validate description
+    desc_match = re.search(r'description:\s*(.+)', frontmatter)
+    if desc_match:
+        description = desc_match.group(1).strip()
+        # Check for angle brackets
+        if '<' in description or '>' in description:
+            return False, 'Description cannot contain angle brackets (< or >)'
+
+    return True, 'Skill is valid!'
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 2:
+        sys.exit(1)
+
+    valid, message = validate_skill(sys.argv[1])
+    sys.exit(0 if valid else 1)