@xonovex/skills 0.1.0

package/commands/plan-update.md

@@ -0,0 +1,99 @@
+---
+description: Update a plan document with the latest implementation status and test results
+allowed-tools:
+  - Read
+  - Edit
+  - Bash
+  - Glob
+  - TaskUpdate
+  - TaskList
+argument-hint: "[document-path] [--dry-run]"
+---
+
+# /plan-update – Update Plan Progress
+
+Updates a plan document with the latest implementation status, test results, and progress.
+
+## Goal
+
+1. **Identifies** the target plan document (auto-detect from git config or argument)
+2. **Updates the plan** with validation results and current progress
+3. **Checks child plan status** (if target has child plans)
+4. **Auto-updates parent** (if target has a parent plan)
+5. **Updates frontmatter** (`status`, `phase`, `updated` date)
+6. **Timestamps** the update for progress tracking
+
+## Arguments
+
+`/plan-update [document-path] [--dry-run]`
+
+- `document-path` (optional): Path to plan document (auto-detects from git config if omitted)
+- `--dry-run` (optional): Preview changes without modifying files
+
+## Core Workflow
+
+1. **Identify Plan**: Auto-detect from git config or use provided path
+2. **Check Type**: Determine if has parent plan or child plans
+3. **Update Status**: Run validation, update frontmatter and status section
+4. **Update Parent**: If has parent plan, auto-update parent
+
+## Updates
+
+**Frontmatter**: `updated`, `status` (in_progress/complete/blocked), `phase`, `completed_date` (if complete)
+
+**Status Section**: Timestamped update with phase, summary, files modified, validation, next steps
+
+## Status Logic
+
+**Child plans** (`type: "plan"`, has `parent_plan`):
+
+- Run validation tests -> update status (complete/in_progress/blocked)
+- Auto-update parent: Read `parent_plan` -> check all siblings -> update parent status
+
+**Parent plans** (`type: "plan"`, `has_subplans: true`):
+
+- If has child plans: All complete -> `complete` | Any blocked -> `blocked` | Else -> `in_progress`
+- If no child plans: Run validation -> update based on results
+
+## Output
+
+```
+Updated plan: plans/auth.md
+
+Status: in_progress -> complete
+Phase: Implementation -> Complete
+Validation: PASS (all tests passing)
+
+Parent plan updates: None (this is a parent plan)
+Files modified: 5 files updated
+
+Next Steps:
+1. Check status: Review updated plan status and validation results
+2. If child plans remain: /plan-continue plans/<plan>.md - Continue with next pending child plan
+3. If all child plans complete: /plan-worktree-validate - Run pre-merge validation
+4. If blocked: Fix identified issues, then /plan-validate to verify
+5. Track progress: /plan-status plans/<plan>.md - Monitor overall completion
+```
+
+## Error Handling
+
+- Error if plan file not found
+- Error if plan format invalid (missing frontmatter)
+- Warning if no changes detected
+- Error if parent plan not found (for child plans)
+
+## Examples
+
+```bash
+# Auto-detect from git config (in feature worktree)
+/plan-update
+
+# Explicit path
+/plan-update plans/auth.md
+
+# Update child plan (auto-updates parent)
+/plan-update plans/auth/02-implementation.md
+
+# Preview changes
+/plan-update plans/auth.md --dry-run
+```

package/commands/plan-validate.md

@@ -0,0 +1,100 @@
+---
+description: Verify that a plan or current work has been fully achieved
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+  - Task
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+argument-hint: "[plan-file] [--detailed]"
+---
+
+# /plan-validate – Validate Plan Achievement
+
+Verify that a plan document's objectives have been fully achieved, or validate that the most recently stated goal in the current conversation has been completed with evidence-based validation.
+
+## Goal
+
+- Validate plan completion with objective tests
+- Check subplan status (if applicable)
+- Report clear pass/fail with evidence
+- Never modify files (read-only)
+
+## Arguments
+
+`/plan-validate [plan-file] [--detailed]`
+
+- `plan-file` (optional): Path to plan document (if omitted, validates current conversation goal)
+- `--detailed` (optional): Comprehensive analysis with full evidence trail
+
+## Core Workflow
+
+### With Plan Document
+
+1. **Load Plan** - Read plan document, extract success criteria from phases
+2. **Parse Metadata** - Extract status, phase, dependencies from frontmatter
+3. **Check Subplans** - If subplans exist, read and report their status
+4. **Design Tests** - Create validation tests for each phase criterion
+5. **Execute Validation Checks** - Run ALL four mandatory checks in order:
+   - Type check: `npx tsc --noEmit` (0 errors)
+   - Linting: `npm run lint` (0 errors, 0 warnings)
+   - Build: `npm run build` (succeeds)
+   - Tests: `npm test` (all pass)
+6. **Report** - Clear pass/fail result with evidence per phase and recommendations
+
+**IMPORTANT**: This command is read-only and never modifies plan files. Use `/plan-update` to update status.
+
+### Without Plan Document (Current Work)
+
+1. **Identify Goal** - Review conversation to extract objective and success criteria
+2. **Design Tests** - Create validation tests for each criterion
+3. **Execute** - Run tests, collect evidence
+4. **Report** - Clear pass/fail result with evidence and recommendations
+
+## Success Criteria
+
+- All phase requirements validated
+- All subplans complete (if subplans exist)
+- All tests pass (typecheck, lint, build, tests)
+- Implementation matches specification
+
+## Output
+
+```
+Validation Report
+
+Phase 1: Setup PASS
+Phase 2: Implementation IN PROGRESS
+  FAIL Error handling incomplete (src/core.ts:45)
+
+Files: PASS typecheck | FAIL lint (2 errors) | PASS test
+
+Result: NOT COMPLETE
+
+Next Steps:
+1. If PASS: /plan-update - Update plan status to reflect completion
+2. If FAIL: Fix identified issues (error handling, lint errors), then re-run validation
+3. Check subplans: /plan-status plans/<plan>.md - See which subplans need work
+4. Continue work: /plan-continue plans/<plan>.md - Resume implementation for incomplete items
+5. Track progress: Monitor validation results in plan status section
+```
+
+## Error Handling
+
+- Error if plan file not found or invalid format
+- Warning if plan already marked complete
+- Info if all tests pass (recommend `/plan-update`)
+
+## Examples
+
+```bash
+# Validate current conversation goal
+/plan-validate
+
+# Validate specific plan
+/plan-validate plans/auth.md
+/plan-validate plans/auth.md --detailed
+```

package/commands/plan-worktree-abandon.md

@@ -0,0 +1,104 @@
+---
+description: Document and abandon a feature with reason and learnings
+model: haiku
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+argument-hint: "[reason] [--remove-worktree] [--no-plan] [--commit] [--dry-run]"
+---
+
+# /plan-worktree-abandon – Abandon Feature with Documentation
+
+Abandon feature by updating plan status, documenting reason, and optionally cleaning up worktree.
+
+## Goal
+
+- Update plan status to "abandoned" with reason and learnings
+- Optionally commit current state and remove worktree
+- Keep worktree by default for later insights extraction
+
+## Arguments
+
+- `reason` (optional): Concise reason for abandonment (prompted if not provided)
+- `--remove-worktree` (optional): Remove feature worktree after documenting
+- `--no-plan` (optional): Skip plan update (for features without plans)
+- `--commit` (optional): Commit current state before abandoning
+- `--dry-run` (optional): Preview changes without modifying files
+
+## Core Workflow
+
+1. Verify in feature worktree (basename matches `*-feature-*`)
+2. Get reason from argument or prompt user
+3. Detect plan via `git config branch.<branch>.plan`
+4. Optionally commit: `git add . && git commit -m "wip: abandoned work on <feature>"` (skipped if --dry-run)
+5. Update plan frontmatter and add "Abandonment Notes" section (or preview if --dry-run)
+6. Keep worktree by default (or remove if `--remove-worktree`, skipped if --dry-run)
+
+## Implementation Steps
+
+1. Verify feature worktree and get current branch
+2. Read plan path from git config
+3. Get abandonment reason (arg or prompt)
+4. Optionally commit (if `--commit` and uncommitted changes)
+5. Update plan (unless `--no-plan`):
+   - Frontmatter: `status: "abandoned"`, `abandoned_reason`, `abandoned_date`
+   - Content: Add "Abandonment Notes" with detailed explanation and learnings
+6. Optionally remove worktree: `git worktree remove <path>`
+
+## Plan Updates
+
+**Frontmatter**:
+
+```yaml
+status: "abandoned"
+abandoned_reason: "Superseded by OAuth 2.0"
+abandoned_date: "2025-11-08"
+```
+
+**Content**:
+
+```markdown
+## Abandonment Notes
+
+**Date**: 2025-11-08
+**Reason**: Superseded by OAuth 2.0
+
+[Detailed explanation and learnings]
+```
+
+## Output
+
+```
+Abandoning feature: auth-custom-jwt
+
+Reason: Superseded by OAuth 2.0
+Plan: Updated (status: abandoned)
+State: Committed as "wip: abandoned work on auth-custom-jwt" (commit b4c5d6e)
+Worktree: Kept (cleanup with /plan-worktree-cleanup)
+
+Next Steps:
+1. Extract insights: /insights-extract abandoned - Capture learnings from abandoned work
+2. Review plan: Check plan's "Abandonment Notes" section for documented reason
+3. Clean up worktree: /plan-worktree-cleanup - Remove abandoned worktree (if kept)
+4. Alternative approach: Create new plan/feature if different approach needed
+5. Share learnings: Document insights in team knowledge base if applicable
+```
+
+## Error Handling
+
+- Error: not in feature worktree, no reason, plan doesn't exist, worktree removal fails
+- Warning: no plan associated (unless `--no-plan`), uncommitted changes (suggest `--commit`)
+
+## Examples
+
+```bash
+/plan-worktree-abandon "Superseded by better approach"
+/plan-worktree-abandon "Requirements changed" --commit --remove-worktree
+/plan-worktree-abandon "Quick experiment" --no-plan
+/plan-worktree-abandon "Blocked by dependency" --commit
+
+# Preview changes without modifying files
+/plan-worktree-abandon "Superseded by OAuth 2.0" --dry-run
+```

package/commands/plan-worktree-create.md

@@ -0,0 +1,92 @@
+---
+description: Create a new git worktree for a feature branch
+model: haiku
+allowed-tools:
+  - Bash
+  - Glob
+  - Read
+argument-hint: "[feature-name] [--from <branch>]"
+---
+
+# /plan-worktree-create – Create Feature Worktree
+
+Creates a new git worktree directory with a feature branch, allowing isolated development without affecting the current worktree.
+
+## Goal
+
+- Detect current worktree name from directory path
+- Create a new sibling worktree directory with a feature branch
+- Follow naming pattern: `<worktree>-feature-<name>` directory with `<worktree>/feature/<name>` branch
+- Store source branch association in git config
+
+## Arguments
+
+`/plan-worktree-create [feature-name] [--from <branch>]`
+
+- `feature-name`: Name of the feature (required) - used in directory and branch names
+- `--from <branch>`: Create feature from specific branch instead of current branch
+
+## Core Workflow
+
+1. **Detect Worktree**: Extract worktree name from current directory path
+2. **Get Source Branch**: Use `--from` argument or current branch via `git branch --show-current`
+3. **Create Worktree**: Use `git worktree add` to create new directory with feature branch
+4. **Store Association**: Save source branch in git config
+
+## Naming Convention
+
+- Worktree directory: `<worktree>-feature-<feature-name>`
+- Branch name: `<worktree>/feature/<feature-name>`
+
+Examples:
+
+- In `services` worktree with feature `auth-fix`:
+  - Directory: `services-feature-auth-fix`
+  - Branch: `services/feature/auth-fix`
+- In `api` worktree with feature `new-endpoint`:
+  - Directory: `api-feature-new-endpoint`
+  - Branch: `api/feature/new-endpoint`
+
+## Implementation Steps
+
+1. **Validate**: Ensure feature name is provided
+2. **Get current directory**: Use `pwd` to get full path
+3. **Extract worktree name**: Parse basename from path (e.g., `/path/to/services` -> `services`)
+4. **Get source branch**: Use `--from` argument or `git branch --show-current`
+5. **Sanitize feature name**: Convert to kebab-case, remove special chars
+6. **Construct names**:
+   - Worktree dir: `../<worktree>-feature-<sanitized-name>`
+   - Branch name: `<worktree>/feature/<sanitized-name>`
+7. **Create worktree**: `git worktree add <worktree-dir> -b <branch-name> <source-branch>`
+8. **Store association**:
+   - `cd <worktree-dir>`
+   - `git config branch.<branch-name>.mergeBackTo <source-branch>`
+
+## Output
+
+```
+Created feature worktree: services-feature-auth-fix
+
+Detected worktree: services
+Source branch: master
+
+Created worktree: /home/user/projects/services-feature-auth-fix
+Created branch: services/feature/auth-fix
+
+Stored associations:
+- Source branch: master
+
+Next Steps:
+1. Navigate: cd ../services-feature-auth-fix
+2. Associate plan: /plan-worktree-set-plan <plan-dir>/<plan>.md (if working with a plan)
+3. Start work: /plan-continue (after associating plan)
+4. Make commits: /plan-worktree-commit
+5. Validate: /plan-worktree-validate
+```
+
+## Error Handling
+
+- Error if feature name not provided
+- Error if worktree directory already exists
+- Error if branch already exists
+- Error if source branch doesn't exist (when using `--from`)

package/commands/plan-worktree-merge.md

@@ -0,0 +1,132 @@
+---
+description: Merge feature worktree back to source worktree
+model: haiku
+allowed-tools:
+  - Bash
+argument-hint: "[--squash] [--remove-worktree] [--delete-remote] [--dry-run]"
+---
+
+# /plan-worktree-merge – Merge Feature Worktree Back to Source
+
+Merges a feature branch from a feature worktree back to its source worktree.
+
+## Goal
+
+- Detect current feature worktree directory
+- Find the source worktree directory
+- Retrieve source branch from git config (stored during creation)
+- Merge feature branch into source branch in source worktree
+- Support both regular merge and squash merge
+- Optionally remove feature worktree after merge
+
+## Arguments
+
+`/plan-worktree-merge [--squash] [--remove-worktree] [--delete-remote] [--dry-run]`
+
+- `--squash`: Squash all feature commits into a single commit
+- `--remove-worktree`: Remove feature worktree directory after merge (default: keep)
+- `--delete-remote`: Also delete remote feature branch (requires remote exists)
+- `--dry-run` (optional): Preview changes without modifying files
+
+## Core Workflow
+
+1. **Validate Feature Worktree**: Verify we're in a `<worktree>-feature-*` directory
+2. **Detect Worktree Names**: Extract base worktree name and feature name from directory
+3. **Retrieve Source Branch**: Get from `git config branch.<feature-branch>.mergeBackTo`
+4. **Navigate to Source**: Find and cd to source worktree directory
+5. **Merge Feature**: Regular (`git merge`) or squash (`git merge --squash` + commit), or preview if --dry-run
+6. **Clean Up**: Optionally remove feature worktree if `--remove-worktree` (skipped if --dry-run)
+
+## Worktree Detection
+
+The command automatically detects:
+
+- Current directory name to identify feature worktree (e.g., `services-feature-hono-openapi`)
+- Base worktree name (e.g., `services`)
+- Source worktree directory (sibling directory, e.g., `../services`)
+- Feature branch from `git branch --show-current`
+- Source branch from `git config branch.<feature-branch>.mergeBackTo`
+
+## Implementation Steps
+
+1. **Get current directory**: `pwd` to get full path, then `basename` to get directory name
+2. **Validate feature worktree**: Ensure directory name matches `*-feature-*` pattern
+3. **Extract names**:
+   - Parse directory name to get base worktree and feature name
+   - Example: `services-feature-hono-openapi` -> worktree: `services`, feature: `hono-openapi`
+4. **Get current branch**: `git branch --show-current`
+5. **Validate feature branch**: Ensure format is `<worktree>/feature/*`
+6. **Get source branch**: `git config branch.<current-branch>.mergeBackTo` or error
+7. **Find source worktree**: Check for `../<base-worktree>` directory
+8. **Verify source exists**: `git -C <source-worktree> rev-parse --verify <source-branch>`
+9. **Check for uncommitted changes**: In current feature worktree, error if uncommitted changes exist
+10. **Navigate to source**: `cd <source-worktree>`
+11. **Checkout source branch**: `git checkout <source-branch>`
+12. **Merge feature**:
+    - Regular: `git merge <feature-branch>`
+    - Squash: `git merge --squash <feature-branch>` then `git commit -m "<message>"`
+13. **Remove worktree**: `git worktree remove <feature-worktree-path>` (only if `--remove-worktree`)
+14. **Delete remote branch**: `git push origin --delete <feature-branch>` (if `--delete-remote`)
+
+## Squash Commit Message
+
+When using `--squash`, generate commit message in format:
+
+```
+<type>: <feature-name-as-description>
+
+Squashed commits from <worktree>/feature/<feature-name>
+```
+
+Example: `feat: introduce hono openapi\n\nSquashed commits from services/feature/hono-openapi`
+
+## Output
+
+```
+Merging feature: services-feature-auth-fix
+
+Detected feature worktree: services-feature-auth-fix
+Base worktree: services
+Feature branch: services/feature/auth-fix
+Source worktree: /home/user/projects/services
+Source branch: master (from git config)
+
+Merge type: Regular merge
+Merge status: Success (no conflicts)
+Worktree cleanup: Kept (use --remove-worktree to clean up)
+
+Next Steps:
+1. Verify merge: Check that changes are properly merged in source worktree
+2. Clean up worktree: /plan-worktree-cleanup - Remove merged feature worktree (if not already removed)
+3. Push changes: Commit and push from source worktree if needed
+4. Delete remote: Use --delete-remote flag if you want to clean up remote branch
+5. If conflicts: Resolve conflicts manually, complete merge, then re-run validation
+```
+
+## Examples
+
+```bash
+# Merge feature branch back to source
+/plan-worktree-merge
+
+# Squash and merge
+/plan-worktree-merge --squash
+
+# Merge and clean up worktree
+/plan-worktree-merge --remove-worktree --delete-remote
+
+# Preview merge without making changes
+/plan-worktree-merge --dry-run
+```
+
+## Error Handling
+
+- Error if not in a feature worktree directory (`*-feature-*` pattern)
+- Error if not on a feature branch (`<worktree>/feature/*`)
+- Error if source branch not stored in git config
+- Error if source worktree directory doesn't exist
+- Error if source branch doesn't exist in source worktree
+- Error if uncommitted changes exist in feature worktree
+- Error if merge conflicts occur - show conflicted files and guidance
+- Error if trying to delete remote branch that doesn't exist
+- Do NOT proceed with worktree removal if merge fails

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@xonovex/skills",
+  "version": "0.1.0",
+  "description": "Xonovex coding guidelines and workflow skills for Claude Code",
+  "license": "MIT",
+  "author": "Xonovex",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xonovex/platform.git",
+    "directory": "packages/plugins/skills"
+  },
+  "bugs": {
+    "url": "https://github.com/xonovex/platform/issues"
+  },
+  "homepage": "https://github.com/xonovex/platform/tree/main/packages/plugins/skills#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    ".claude-plugin/plugin.json",
+    "skills",
+    "commands"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "skills",
+    "guidelines",
+    "typescript",
+    "react",
+    "docker",
+    "kubernetes",
+    "terraform"
+  ],
+  "scripts": {
+    "build": "echo 'No build needed for plugin package'",
+    "lint": "echo 'No linting needed for plugin package'",
+    "fmt": "prettier --write .",
+    "fmt:check": "prettier --check .",
+    "typecheck": "echo 'No typechecking needed for plugin package'",
+    "test": "echo 'No tests for plugin package'"
+  }
+}

package/skills/astro-guidelines/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: astro-guidelines
+description: >-
+  Trigger on `.astro` files. Use when building Astro static sites with islands architecture. Apply for content collections, component hydration, or accessibility implementation. Keywords: Astro, islands, static HTML, content collections, `astro:content`, schema validation.
+---
+
+# Astro Coding Guidelines
+
+## Essentials
+
+- **Islands architecture** - Default to static HTML, hydrate only where needed, see [reference/islands-architecture.md](reference/islands-architecture.md)
+- **Project structure** - Use `src/pages`, `src/components`, `src/layouts`, `src/content`, see [reference/project-structure.md](reference/project-structure.md)
+- **Content collections** - Use `astro:content` with schema-validated frontmatter, see [reference/content-collections.md](reference/content-collections.md)
+- **Framework components** - Integrate React, Vue, or other frameworks, see [reference/components.md](reference/components.md)
+- **Accessibility** - Use semantic HTML, alt text, ARIA as needed, see [reference/accessibility.md](reference/accessibility.md)
+
+## Progressive disclosure
+
+- Read [reference/islands-architecture.md](reference/islands-architecture.md) - When deciding which components need client-side JavaScript
+- Read [reference/project-structure.md](reference/project-structure.md) - When organizing files and directories
+- Read [reference/content-collections.md](reference/content-collections.md) - When managing blog posts, docs, or structured content
+- Read [reference/components.md](reference/components.md) - When integrating React, Vue, or other framework components
+- Read [reference/accessibility.md](reference/accessibility.md) - When adding keyboard navigation or screen reader support

package/skills/astro-guidelines/reference/accessibility.md

@@ -0,0 +1,31 @@
+# accessibility: Accessibility Best Practices
+
+**Guideline:** Use semantic HTML, descriptive alt text, and ARIA attributes for accessibility.
+
+**Rationale:** Static-first approach enables accessible sites by default; semantic HTML ensures assistive tech compatibility and improves SEO.
+
+**Example:**
+
+```astro
+<header>
+  <nav aria-label="Main navigation">
+    <ul><li><a href="/">Home</a></li></ul>
+  </nav>
+</header>
+
+<main>
+  <article>
+    <h1>Title</h1>
+    <Image src={image} alt="Descriptive text" />
+    <section><h2>Section</h2></section>
+  </article>
+  <aside aria-label="Related">...</aside>
+</main>
+```
+
+**Techniques:**
+- Semantic elements: Use `<header>`, `<nav>`, `<main>`, `<article>`, `<aside>` for structure
+- Alt text: Provide descriptive alt attributes for all images
+- Heading hierarchy: Maintain h1 → h2 → h3 logical ordering
+- ARIA labels: Add `aria-label` to navigation and complex regions
+- Navigation region: Use `<nav aria-label>` for clear landmark structure

package/skills/astro-guidelines/reference/components.md

@@ -0,0 +1,42 @@
+# components: Component Development and Composition
+
+**Guideline:** Build reusable Astro components with props and slots; use framework components only for interactivity.
+
+**Rationale:** Astro components for static content, framework components (React, Vue, Svelte) for interactive features; minimizes JavaScript.
+
+**Example:**
+
+```astro
+---
+// Card.astro
+interface Props {
+  title: string;
+  description?: string;
+  href?: string;
+  variant?: "default" | "featured";
+}
+
+const { title, description, href, variant = "default" } = Astro.props;
+---
+<div class={`card card--${variant}`}>
+  <h3>{title}</h3>
+  {description && <p>{description}</p>}
+  <div class="card__content"><slot /></div>
+  <div class="card__footer">
+    <slot name="footer">
+      {href && <a href={href}>Learn more →</a>}
+    </slot>
+  </div>
+</div>
+<style>
+  .card { border: 1px solid #ddd; padding: 1rem; border-radius: 8px; }
+  .card--featured { border-color: #0066cc; background: #f0f8ff; }
+</style>
+```
+
+**Techniques:**
+- Astro components: Create `.astro` components for static presentational UI
+- Props typing: Use TypeScript interfaces for type-safe component props
+- Slots composition: Leverage slots for flexible component composition
+- Framework separation: Import framework components only for interactivity
+- Scoped styles: Use `<style>` blocks for component-scoped CSS