@xonovex/skills 0.1.0

package/commands/plan-continue.md

@@ -0,0 +1,167 @@
+---
+description: Resume work from an existing plan document with full context loading
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - TaskCreate
+  - TaskUpdate
+  - TaskList
+  - Task
+argument-hint: "[document-path]"
+---
+
+# /plan-continue – Continue Progress from Plan
+
+Resumes work from an existing plan document by loading its context and outlining the next steps. Auto-detects associated plan from git config if available.
+
+## Goal
+
+**Start working IMMEDIATELY. No questions, no asking for permission, no confirmations.**
+
+**ONE plan only. When complete, STOP. User re-runs `/plan-continue` for next plan.**
+
+- Auto-detect plan from git config or use provided path
+- Find first actionable child plan (if parent has subplans)
+- Execute that single plan to completion
+- Mark complete, report success, STOP
+
+## Arguments
+
+`/plan-continue [document-path]`
+
+- `document-path` (optional): Path to plan document. Resolution order if omitted:
+  1. Check git config for associated plan (feature worktree)
+  2. **Use current conversation context** - if a `/plan-create`, `/plan-research-*`, or similar command was run earlier in this conversation, continue from that research/plan. Do NOT search for other plans.
+  3. Only if no context exists: Ask user which plan to continue
+
+## Core Workflow
+
+1. **Resolve Plan**: Check git config, then conversation context (do NOT search for plans)
+2. **Load Parent Plan**: Parse plan document and extract metadata
+3. **Find Next Actionable Plan**: Find first child plan with `pending` or `in_progress` status
+4. **Load and Execute**: Read the target plan fully and implement it
+5. **Complete and STOP**: Mark plan complete, update status, report success, then STOP
+
+## Implementation Steps
+
+**IMPORTANT: Work on ONE plan at a time. Do NOT read all child plans upfront.**
+
+1. **Resolve Plan** (if no document-path provided):
+   - First, check git config: `git config branch.$(git branch --show-current).plan`
+   - If no git config, **use conversation context** - look at what was discussed/researched earlier in this conversation (e.g., `/plan-research-*` output, `/plan-create` result). Implement that work directly.
+   - Only if truly no context: Ask user which plan to work on. Do NOT glob/search for plans unprompted.
+
+2. **Load Parent Plan Metadata-Only**: Read only the first 30 lines (front matter section)
+   - Extract `has_subplans`, `status`, and `parallel_group` fields
+   - Do NOT read the entire plan file
+
+3. **Find Next Actionable Child Plan** (if `has_subplans: true`):
+   - List child plan files in `plans/<plan-name>/` directory
+   - For each child in order (01, 02, 03...), read only the first 30 lines to get `status`
+   - Stop at FIRST plan with `status: "in_progress"` or `status: "pending"`
+   - Do NOT read remaining child plans
+
+4. **Determine Work Target**:
+   - If parent plan `status: "complete"`: Warn user and exit
+   - If found actionable child plan: That becomes the work target
+   - If all checked child plans are complete: Recommend `/plan-update` to mark parent complete
+   - If no child plans: Parent plan is the work target
+
+5. **Load Work Target Plan**: Read ONLY the selected plan in full (not all plans)
+6. **Analyze Current Status**:
+   - Extract phase, status, completed tasks from selected document
+   - Identify pending tasks and blockers
+7. **Validate State**:
+   - Check if files mentioned in plan exist
+   - Run type checking if applicable
+   - Run linting to check code style
+   - Run tests if test commands specified
+   - Report baseline status (typecheck, lint, build, tests)
+8. **Consult Skills**: Check plan frontmatter for `skills_to_consult` array and invoke relevant skills before implementation
+9. **Generate Next Steps**:
+   - Identify highest priority pending tasks for current plan only
+   - Extract file locations and required changes
+   - Create implementation order based on dependencies
+10. **Create Tasks**: Use TaskCreate to set up actionable tasks with status tracking; update with TaskUpdate as work progresses
+11. **Execute Plan**: Implement all tasks in the plan
+12. **On Completion**:
+
+- Update plan status to `complete` in front matter
+- Run validation (typecheck, lint, build, tests)
+- Report completion summary
+- **STOP** - do not continue to next plan automatically
+
+## Output
+
+**Initial Briefing**:
+
+```
+Continuing plan: plans/authentication.md
+
+Plan: Authentication System
+Progress: 2/4 child plans complete
+Current: 03-api-routes.md (in_progress)
+
+Validation:
+  [PASS] Typecheck: PASS
+  [PASS] Lint: PASS
+  [PASS] Build: PASS
+  [WARN] Tests: 2 failing (expected - not yet implemented)
+
+Next Steps:
+1. Implement POST /api/auth/login route
+2. Add session middleware
+3. Create auth guards
+
+Files to modify:
+- src/routes/auth/login.ts
+- src/middleware/session.ts
+- src/guards/auth.ts
+```
+
+**Completion Report**:
+
+```
+Completed plan: plans/authentication/03-api-routes.md
+
+Implementation Summary:
+- Added 3 API routes (login, logout, refresh)
+- Created session middleware with JWT validation
+- Implemented auth guards for protected routes
+
+Validation:
+  [PASS] Typecheck: PASS
+  [PASS] Lint: PASS
+  [PASS] Build: PASS
+  [PASS] Tests: PASS (12 tests)
+
+Status: in_progress -> complete
+Parent: plans/authentication.md (3/4 complete)
+
+Next Steps:
+1. Run /plan-continue for next child plan
+2. Or /plan-status to check overall progress
+```
+
+## Error Handling
+
+- If no git config and no conversation context: Ask user which plan to continue
+- Error if specified document-path doesn't exist
+- **Warning if plan `status: "complete"`** (all work done, recommend `/plan-validate` or `/plan-update`)
+- **Info if all child plans complete** (recommend `/plan-update` to mark parent complete)
+- Error if plan file is malformed (invalid front matter)
+- Warning if no plan associated with feature worktree
+
+## Examples
+
+```bash
+# Auto-detect from git config (in feature worktree)
+/plan-continue
+
+# Explicit path
+/plan-continue plans/authentication.md
+
+# Continue specific subplan
+/plan-continue plans/authentication/subplan-02.md
+```

package/commands/plan-create.md

@@ -0,0 +1,107 @@
+---
+description: >-
+  Create a high-level plan with research for user review before detailed
+  subplans
+allowed-tools:
+  - Write
+  - Read
+  - Glob
+  - Grep
+  - TaskCreate
+  - TaskUpdate
+  - AskUserQuestion
+argument-hint: "[spec-file-or-requirements] [--interactive] [--depends-on <plan>] [--dry-run]"
+---
+
+# /plan-create – Create Plan with Research
+
+Generate high-level plan from spec/requirements using deep codebase and web research. Presents architecture decisions for user review BEFORE generating detailed subplans.
+
+## Prerequisites
+
+Run research before using this command:
+
+- `/plan-research` - General codebase and web research
+- `/code-simplify` - Code simplification analysis
+- `/code-harden` - Code hardening analysis
+- Or other `/plan-research-*` commands as appropriate
+
+This command assumes research context is already in the conversation. It does NOT perform codebase exploration.
+
+## Goal
+
+- Generate plan with architecture decisions and technology choices from conversation context
+- Present plan for user review/discussion
+- Save plan and STOP (user reviews, then runs /plan-subplans-create)
+
+## Arguments
+
+- `spec-file-or-requirements` (optional): Path to spec or inline requirements (defaults to conversation context)
+- `--interactive` (optional): Ask context-dependent technical questions during research
+- `--depends-on <plan>` (optional): Mark dependency on another plan
+- `--dry-run` (optional): Preview without writing files
+
+## Core Workflow
+
+**IMPORTANT: Do NOT use EnterPlanMode. Do NOT use Task/Explore agents - assume research is already done.**
+
+1. **Gather requirements**: Read spec file or analyze conversation context; ask clarifications if `--interactive`
+2. **Synthesize context**: Use research findings from conversation context
+3. **Document key decisions**: Technology choices with versions, rationale, alternatives
+4. **Assess risks**: Trade-offs, alternatives considered, open questions
+5. **Propose subplan structure**: List subplan names without detailed implementation
+6. **Write plan**: Save to `plans/<feature-name>.md` (standalone file, NOT inside existing plan directories unless explicitly requested)
+7. **Show summary**: Display plan for user review; STOP (no subplans, no implementation)
+
+## Implementation Details
+
+**Interactive Mode**: Ask about architectural preferences, library choices, error handling, testing depth, accessibility
+
+**Plan Frontmatter**: `type: plan`, `has_subplans: true`, `status: pending-approval`, `dependencies.plans: []`, `proposed_subplans: []`, `skills_to_consult: [skill-names]`, `research_sources: {documentation: [], versions: {}}`
+
+**Skills to Consult**: Plan MUST include `skills_to_consult` array listing applicable coding guidelines based on languages/frameworks (e.g., `typescript-guidelines`, `react-guidelines`, `testing-guidelines`). This ensures implementers know which project conventions to follow.
+
+**Plan Sections**: Overview (2-3 sentences), Goals (bullet list), Current State (stack/integration), Research Findings (recommended library with version/rationale/pros-cons/docs, alternatives), Proposed Approach (numbered list of components/files), Risk Assessment, Proposed Child Plans (with execution groups), Success Criteria, Estimated Effort
+
+## Output
+
+```
+Created plan: plans/feature-name.md
+
+Research Summary:
+- Analyzed codebase: 15 files in services/packages/example
+- Current stack: React 19, Astro 5.15, Tailwind 4.1
+- Recommended: canvas-confetti@1.9.3 (latest stable)
+- Documentation: https://example.com/docs
+
+Plan Summary:
+- Goals: Add celebration animation on form submission
+- Approach: 3 components (library, modal, integration)
+- Proposed Child Plans: 4 (2 parallel, 2 sequential)
+- Estimated Effort: 2-3 hours
+
+Next Steps:
+1. Review the plan for architecture decisions and technology choices
+2. Discuss and evaluate research findings, alternatives, and trade-offs
+3. Verify proposed child plan structure and execution groups
+4. Generate child plans: /plan-subplans-create plans/feature-name.md
+5. Alternative: Modify plan if different approach needed, then re-run child plan creation
+```
+
+## Examples
+
+```bash
+# Create plan with research
+/plan-create specs/feature.md
+
+# Interactive with questions
+/plan-create --interactive
+
+# With dependency
+/plan-create specs/profile.md --depends-on plans/auth.md
+```
+
+## Error Handling
+
+- Error: spec doesn't exist, plan exists, output dir fails
+- Warning: no requirements, dependency missing, library research failed

package/commands/plan-research.md

@@ -0,0 +1,113 @@
+---
+description: Research codebase and web for requirements without creating a plan
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - TaskCreate
+  - TaskUpdate
+  - WebSearch
+  - WebFetch
+  - AskUserQuestion
+argument-hint: "<requirements> [--interactive] [--save-to <file>]"
+---
+
+# /plan-research – Research Codebase and Web
+
+Research codebase and web for requirements, presenting findings for review. Does NOT create plans - run `/plan-create` afterward to create an implementation plan.
+
+## Goal
+
+- Use Task/Explore agents to understand codebase (do NOT use EnterPlanMode)
+- Use WebSearch/WebFetch for latest library versions and documentation
+- Present research findings for review
+- NO plan file created (unless `--save-to` specified)
+
+## Arguments
+
+- `requirements` (required): Description of what to research
+- `--interactive` (optional): Ask clarifying questions
+- `--save-to <file>` (optional): Save research to file
+
+## Core Workflow
+
+**Use Task agents with subagent_type=Explore and model=haiku for codebase analysis. Do NOT use EnterPlanMode.**
+
+1. **Gather requirements**: Parse input; ask clarifications if `--interactive`
+
+2. **Codebase exploration**: Use Task with subagent_type=Explore and model=haiku (up to 3 parallel):
+   - Architecture, patterns, integration points
+   - Existing library versions, similar implementations
+   - Testing/build patterns, applicable coding guidelines
+
+3. **Web research**: WebSearch for latest versions, WebFetch for docs
+
+4. **Synthesize findings**: Combine codebase + web research
+
+5. **Present or save**: Display findings OR save to file
+
+## Implementation Details
+
+**Version detection**: package.json -> WebSearch latest -> WebFetch docs
+
+**Interactive mode**: Ask about preferences, libraries, error handling, testing depth
+
+**Research output**: Current stack, recommended libraries (with versions/rationale), code locations, integration points, skills to consult, considerations
+
+## Output
+
+```
+Research: Add rate limiting to API
+
+Current Stack:
+- Hono 4.0.2, Redis 4.6.0
+
+Code Locations:
+- Middleware pattern: packages/api/src/middleware/
+- Similar: packages/auth/src/middleware/throttle.ts
+
+Recommended:
+- @upstash/ratelimit@1.0.0 (latest stable)
+- https://upstash.com/docs/ratelimit
+- Fits existing Redis infrastructure
+
+Integration Points:
+- Add to Hono middleware chain
+- Use existing Redis connection
+
+Skills: typescript-guidelines, hono-guidelines
+
+Considerations: Rate limit keys per user/IP, env config, metrics
+```
+
+## Examples
+
+```bash
+/plan-research "Add rate limiting to API"
+/plan-research "Implement WebSocket support" --interactive
+/plan-research "Add analytics tracking" --save-to research/analytics.md
+```
+
+## Integration
+
+```bash
+/plan-research "Add rate limiting"       # Explore options
+/plan-create "Add rate limiting"         # Create plan
+/plan-subplans-create plans/rate-limit.md  # Generate subplans
+```
+
+**When to use**: Exploring options, researching unfamiliar tech, saving research without plan
+
+**vs. other commands**:
+
+- `/plan-create`: Research + create plan file
+- `/plan-research`: Research only (or save separately)
+- `/plan-followup`: Create follow-up sibling plan
+
+## Error Handling
+
+- **Error**: Requirements unclear, web research fails
+- **Warning**: No existing patterns found, library version conflicts
+- **Info**: Research saved to file, using cached results

package/commands/plan-subplans-create.md

@@ -0,0 +1,111 @@
+---
+description: >-
+  Generate detailed subplans from an approved parent plan with parallel
+  execution detection
+model: sonnet
+allowed-tools:
+  - Write
+  - Read
+  - Glob
+  - Grep
+  - TaskCreate
+  - TaskUpdate
+argument-hint: "[parent-plan-file] [--by-phase] [--dry-run]"
+---
+
+# /plan-subplans-create – Generate Detailed Subplans from Parent Plan
+
+Generate detailed implementation subplans from an approved parent plan with parallel execution detection based on file/package dependencies.
+
+## Prerequisites
+
+Run before using this command:
+
+- `/plan-create` - Create and get approval for the parent plan
+
+This command requires an approved parent plan. It does NOT perform codebase exploration - it relies on the parent plan context.
+
+## Goal
+
+- Read approved parent plan and extract proposed subplan structure
+- Generate detailed child plans with implementation steps, code snippets, validation
+- Detect parallel execution groups based on file/package overlap analysis
+- Auto-associate with feature worktree via git config
+- Save child plans and STOP (user runs /plan-continue when ready)
+
+## Arguments
+
+- `parent-plan-file` (required): Path to approved parent plan (e.g., `plans/auth.md`)
+- `--by-phase` (optional): Split by phase markers instead of logical grouping
+- `--dry-run` (optional): Preview without writing files
+
+## Core Workflow
+
+**IMPORTANT: Do NOT use EnterPlanMode. Do NOT use Task/Explore agents - rely on parent plan context.**
+
+1. **Read parent plan**: Load and parse approved parent plan
+2. **Validate status**: Ensure parent plan is approved (status: `pending-approval` or `approved`)
+3. **Extract context**: Goals, technology choices, proposed subplans, dependencies
+4. **Identify child plans**: Use proposed subplan structure from parent plan
+5. **Generate detailed content**: Objective, tasks with code snippets, file paths/line numbers, validation steps (typecheck/lint/build/test/integration), success criteria
+6. **Analyze dependencies**: File overlap analysis -> parallel groups (independent), sequential (overlapping/dependent)
+7. **Write child plan files**: Save to `<plan-dir>/<feature-name>/subplan-*.md`
+8. **Update parent plan**: Add parallel_groups and dependencies.subplans
+9. **Auto-associate worktree**: Set `git config branch.<branch>.plan` if in feature worktree
+10. **Show summary**: Display created child plans and execution strategy; STOP (no implementation)
+
+## Implementation Details
+
+**Splitting**: Logical grouping (default) or by phase markers (`--by-phase`)
+
+**Dependency Detection**: File overlap -> Sequential; No overlap -> Parallel; Explicit deps -> Sequential with tracking
+
+**Child Plan Frontmatter**: `type: plan`, `has_subplans: false`, `parent_plan`, `parallel_group`, `status: pending`, `dependencies: {plans: [], files: []}`, `skills_to_consult: [skill-names]`, `validation: {type_check: pending, lint: pending, build: pending, tests: pending, integration: pending}`
+
+**Skills to Consult**: Every child plan MUST include `skills_to_consult` array listing applicable coding guidelines (e.g., `typescript-guidelines`, `testing-guidelines`, `hono-guidelines`). This ensures implementers consult project conventions before coding.
+
+**Child Plan Sections**: Objective, Tasks (numbered with file paths, code snippets, actions), Validation Steps (typecheck, lint, build, test - all must pass), Success Criteria (checklist), Files Modified/Created (list), Dependencies (required plans), Estimated Duration
+
+## Output
+
+```
+Created child plans for: plans/feature-name.md
+
+Child Plans Created:
+- plans/feature-name/01-add-library.md (pending)
+- plans/feature-name/02-create-component.md (pending)
+- plans/feature-name/03-integrate.md (pending)
+- plans/feature-name/04-add-tests.md (pending)
+
+Execution Strategy:
+- Parallel Group 1: 01-add-library, 02-create-component
+- Sequential Group 2: 03-integrate (depends on Group 1)
+- Sequential Group 3: 04-add-tests (depends on Group 2)
+
+Updated parent plan with parallel execution groups
+
+Next Steps:
+1. Review all child plans
+2. Verify parallel execution groups and dependencies
+3. Create workspace: /plan-worktree-create feature-name --plan plans/feature-name.md
+4. Start implementation: /plan-continue plans/feature-name.md
+5. Track progress: /plan-status plans/feature-name.md
+```
+
+## Examples
+
+```bash
+# Generate child plans from approved parent plan
+/plan-subplans-create plans/feature.md
+
+# Phase-based splitting
+/plan-subplans-create plans/migration.md --by-phase
+
+# Preview without writing
+/plan-subplans-create plans/feature.md --dry-run
+```
+
+## Error Handling
+
+- Error: parent plan doesn't exist, parent plan not approved, child plans already exist, output dir fails
+- Warning: >10 child plans (consider consolidation), circular dependencies, excessive file overlap

package/commands/plan-tdd-create.md

@@ -0,0 +1,128 @@
+---
+description: >-
+  Create a high-level TDD plan with research for user review before detailed
+  step generation
+allowed-tools:
+  - Write
+  - Read
+  - Glob
+  - Grep
+  - TaskCreate
+  - TaskUpdate
+  - AskUserQuestion
+argument-hint: "[spec-file-or-requirements] [--interactive] [--depends-on <plan>] [--dry-run]"
+---
+
+# /plan-tdd-create – Create TDD Plan with Research
+
+Generate high-level TDD plan for user review BEFORE detailed RED-GREEN-COMMIT generation. For complex features with multiple stories.
+
+## Prerequisites
+
+Run research before using this command:
+
+- `/plan-research` - General codebase and web research
+- `/code-simplify` - Code simplification analysis
+- `/code-harden` - Code hardening analysis
+- Or other `/plan-research-*` commands as appropriate
+
+This command assumes research context is already in the conversation. It does NOT perform codebase exploration.
+
+## Goal
+
+- Break requirements into stories with atomic test step proposals from conversation context
+- Present test strategy for review
+- Save plan and STOP (user approves, then runs /plan-tdd-subplans-create)
+
+## Arguments
+
+- `spec-file-or-requirements` (optional): Path to spec or inline requirements (defaults to context)
+- `--interactive` (optional): Ask about test approach and step granularity
+- `--depends-on <plan>` (optional): Mark dependency on another plan
+- `--dry-run` (optional): Preview without writing
+
+## Core Workflow
+
+**IMPORTANT: Do NOT use EnterPlanMode. Do NOT use Task/Explore agents - assume research is already done.**
+
+1. **Gather context**: Read spec; use research findings from conversation context
+2. **Decompose**: Identify stories, propose atomic test steps (one test = one commit), note file impacts, identify dependencies
+3. **Document**: Write plan with research findings, proposed steps table, reference files, open questions
+4. **Save**: Write to `plans/<feature>-tdd.md` (standalone file, NOT inside existing plan directories unless explicitly requested); STOP for user review
+
+## Plan Structure
+
+```markdown
+# [Feature] TDD Plan
+
+**Frontmatter:**
+type: plan
+has_subplans: true
+status: pending-approval
+
+## Overview
+
+[Description and approach]
+
+**Status:** pending-approval
+
+## Skills to Consult
+
+- [Language/framework-specific guidelines]
+
+## Research Findings
+
+- **Test Framework:** [Project's test framework]
+- **Test Organization:** [conventions]
+- **Validation Pattern:** [Project's validation approach]
+- **Architecture:** [Project's architecture style]
+- **Reference:** `path/to/reference-test-file`
+
+### Package Structure
+
+**Location:** `package-path`
+[Project directory structure]
+
+## Stories & Proposed Steps
+
+### Story 1: [Name]
+
+| Step | Test Description | Files   |
+| ---- | ---------------- | ------- |
+| 1.1  | [Test verifies]  | [files] |
+
+### Story 2: [Name]
+
+...
+
+## Execution Strategy
+
+- Dependencies: [order, parallel opportunities]
+- Estimated: Story 1 (N steps), Story 2 (M steps), Total (X commits)
+
+## Risk Assessment
+
+- Complex areas, edge cases, validation needs
+- **Open Questions:** [clarifications needed]
+
+## Next Steps
+
+After approval: `/plan-tdd-subplans-create plans/[feature]-tdd.md`
+```
+
+## Step Patterns
+
+**New components:** Basic creation test -> Property tests -> Behavior tests -> Edge cases -> Validation tests
+
+**Extending components:** New property/behavior test -> Integration -> Edge cases
+
+**Granularity check:** Independent commit? Tests ONE thing? Clear description?
+
+## Examples
+
+```bash
+/plan-tdd-create specs/feature.md
+/plan-tdd-create --interactive
+/plan-tdd-create specs/logic.md --depends-on plans/setup-tdd.md
+/plan-tdd-create "Add auth" --dry-run
+```