Contributing to jaan.to

Thank you for your interest in contributing to jaan.to! This document outlines how to contribute effectively to the project.

Table of Contents​

• Branching Strategy
• Code of Conduct
• Ways to Contribute
• Adding New Skills
• Improving Learning Files
• Code Style & Conventions
• Testing Guidelines
• Submitting Changes
• Release Process

Branching Strategy​

jaan.to uses a two-branch development model:

Branches​

Workflow​

feature/* ───> dev ───> main
                │         │
                │    (PR + review)
                │         │
                │    (release tag)
                │         │
                └─────────┘
               sync dev

1. Daily development: Work on dev branch (direct pushes allowed)
2. Feature work: Create feature branches from dev, merge back to dev
3. Releases: Create PR from dev → main (requires review + CI checks)
4. After release: Sync dev from main, then bump to next version (e.g., 3.15.0 → 3.16.0)

Contributing to dev​

# Clone and switch to dev
git clone https://github.com/parhumm/jaan-to.git
cd jaan-to
git checkout dev

# Make changes, test locally
claude --plugin-dir .

# Push to dev (no PR required for small changes)
git push origin dev

Hotfixes​

All fixes go through dev first:

1. Fix on dev
2. Test
3. Create expedited PR: dev → main

Code of Conduct​

• Be respectful: Treat everyone with respect and kindness
• Be collaborative: Work together to improve the project
• Be constructive: Provide helpful feedback and suggestions
• Be inclusive: Welcome contributors of all backgrounds and experience levels

Ways to Contribute​

1. Report Bugs​

Found a bug? Open an issue with:

• Description: What happened vs what you expected
• Steps to reproduce: Exact commands and inputs
• Environment: OS, Claude Code version, plugin version
• Logs: Error messages or relevant output

2. Suggest Features​

Have an idea? Open an issue with:

• Use case: What problem does this solve?
• Proposed solution: How should it work?
• Alternatives: Other ways to solve the problem
• Impact: Who benefits and how?

3. Improve Documentation​

Documentation improvements are always welcome:

• Fix typos or unclear explanations
• Add examples or use cases
• Update outdated information
• Improve README or skill descriptions

4. Add Skills​

See Adding New Skills below.

5. Capture Lessons​

After using a skill, share what you learned:

• Common mistakes you encountered
• Edge cases you discovered
• Improvements you'd suggest

See Improving Learning Files below.

Adding New Skills​

Quick Start​

The easiest way to create a new skill:

# From Claude Code
/jaan-to:skill-create

This wizard will guide you through:

1. Choosing a role and domain
2. Defining inputs and outputs
3. Describing the skill behavior
4. Creating the skill structure

Manual Process​

If you prefer to create skills manually, follow the Creating Skills Guide.

Key Requirements:

1. SKILL.md file with YAML frontmatter:

   ---
   name: skill-name
   description: Brief description in third-person voice
   ---
   

2. Naming convention:

   • Public skills: {role}-{domain}-{action}
   • Internal skills: {domain}-{action}

3. Two-phase workflow:

   • Phase 1: Read-only analysis (context, requirements, planning)
   • HARD STOP: Confirm with user before proceeding
   • Phase 2: Generation (write files, validate, preview)

4. LEARN.md file (optional but recommended):

   • Location: skills/{name}/LEARN.md
   • Format: See docs/learning/LESSON-TEMPLATE.md

5. template.md file (if skill generates structured output):

   • Location: skills/{name}/template.md
   • Format: Markdown with {{placeholders}}

Skill Categories​

Testing Your Skill​

1. Install plugin locally:

   claude --plugin-dir /path/to/jaan-to
   

2. Verify skill appears:

   /help | grep your-skill-name
   

3. Test execution:

   /jaan-to:your-skill-name "test input"
   

4. Run verification:

   ./scripts/verify-install.sh /path/to/test-project --plugin-dir /path/to/jaan-to
   

Improving Learning Files​

Learning files (LEARN.md) capture accumulated wisdom from skill usage. These files make skills smarter over time.

Adding Lessons​

Via Command (Recommended):

/jaan-to:learn-add "lesson content here"

Manual Edit:

1. Edit jaan-to/learn/{skill-name}.learn.md in your project
2. Follow format from docs/learning/LESSON-TEMPLATE.md

Lesson Structure​

## [Brief Title of Lesson]

**Date:** 2026-02-03
**Skill:** skill-name
**Severity:** [Low | Medium | High | Critical]

### Context
[What were you trying to do?]

### What Happened
[What went wrong or what was learned?]

### Root Cause
[Why did it happen?]

### Fix
[How was it resolved?]

### Prevention
[How to avoid this in the future?]

What Makes a Good Lesson​

✅ Good:

• Specific: "PRD missing Security section for OAuth flows"
• Actionable: "Add validation: check for Security section when OAuth mentioned"
• Contextual: "User requested OAuth integration but PRD had no security considerations"

❌ Bad:

• Vague: "PRD was incomplete"
• Not actionable: "Should be better"
• No context: "It didn't work"

Code Style & Conventions​

Naming​

Skills:

• Directory: skills/jaan-to:pm-prd-write/
• File: SKILL.md (uppercase)
• Command: /jaan-to:pm-prd-write
• Logical name: jaan-to:pm-prd-write

Files:

• Markdown: README.md, CHANGELOG.md, CONTRIBUTING.md (uppercase for root docs)
• Scripts: bootstrap.sh, learning-summary.sh (lowercase, kebab-case)
• Templates: template.md (lowercase)

Shell Scripts​

• Use #!/bin/bash or #!/usr/bin/env bash
• Always include set -euo pipefail for safety
• Use ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths
• Use ${CLAUDE_PROJECT_DIR} for project-relative paths
• Exit 0 on success, non-zero on error

Example:

#!/bin/bash
set -euo pipefail

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(dirname "$0")/..}"

# Your code here

exit 0

Dual-Platform Rule (Claude + Codex)​

Feature changes must keep shared logic platform-neutral and compatible with both runtimes.

• Put feature behavior in shared core paths:
  • skills/, scripts/, agents/, config/, docs/extending/
• Limit runtime-specific behavior to adapter files:
  • Claude: .claude-plugin/, hooks/, CLAUDE.md
  • Codex: adapters/codex/AGENTS.md, adapters/codex/jaan-to
• Avoid adding platform-specific instructions directly inside skills/*/SKILL.md

Markdown​

• Use ATX headers (#, ##, not underlines)
• Max line length: 120 characters (soft limit)
• Code blocks: Always specify language (bash, json, ```yaml)
• Links: Use reference-style for repeated URLs

YAML Frontmatter​

• Always use --- delimiters
• Required fields first (name, description)
• Optional fields after
• No custom fields without documentation

Example:

---
name: skill-name
description: Brief description
---

Testing Guidelines​

Automated Tests​

jaan.to uses script-driven automated validation and E2E checks for both Claude and Codex runtimes.

Core E2E entrypoints:

bash scripts/test/e2e-dual-runtime-smoke.sh
bash scripts/test/e2e-dual-runtime-full.sh

Manual Testing Checklist​

Before submitting a PR with a new skill:

• Skill appears in /help output
• Skill executes without errors
• Two-phase workflow works (HARD STOP between phases)
• Output written to correct location (jaan-to/outputs/)
• LEARN.md seed file exists
• Template file exists (if applicable)
• Context files are read correctly (tech.md, team.md, etc.)
• Quality checks pass (if applicable)
• Skill description uses third-person voice
• Command naming follows convention

Integration Testing​

Test skills work together:

# Example: PRD → Stories → Tasks workflow
/jaan-to:pm-prd-write "user authentication"
/jaan-to:pm-story-write from prd
/jaan-to:frontend-task-breakdown from prd

Verify:

• Stories reference PRD correctly
• Tasks reference PRD and Stories correctly
• No broken file paths
• Cross-skill suggestions work

Multi-Runtime Validation (Required for Feature Changes)​

Before opening a PR, run:

bash scripts/test/e2e-dual-runtime-smoke.sh
bash scripts/validate-multi-runtime.sh
bash scripts/validate-claude-compat.sh
bash scripts/validate-codex-runner.sh

This validates that both distribution targets build and stay in sync:

• dist/jaan-to-claude
• dist/jaan-to-codex

For pull requests, dual-runtime checks are required by CI:

• Reusable gate workflow: .github/workflows/_dual-runtime-gate.yml
• PR to dev: .github/workflows/dev-dist-build.yml
• PR to main: .github/workflows/release-check.yml
• Push monitor (non-blocking): .github/workflows/dev-push-monitor.yml
• Nightly full-suite monitor (non-blocking): .github/workflows/nightly-e2e.yml

Submitting Changes​

1. Fork and Clone​

git clone https://github.com/YOUR-USERNAME/jaan-to.git
cd jaan-to
git remote add upstream https://github.com/parhumm/jaan-to.git

2. Create a Branch from dev​

# Always branch from dev, not main
git checkout dev
git pull upstream dev
git checkout -b feature/your-skill-name
# or
git checkout -b fix/issue-description

Branch naming:

• Features: feature/skill-name or feature/description
• Fixes: fix/issue-description
• Docs: docs/what-changed
• Refactor: refactor/what-changed

3. Make Changes​

Follow guidelines above for code style, testing, and documentation.

4. Commit​

Commit message format:

type(scope): brief description

Longer explanation if needed.

- Bullet points for details
- More details

Co-authored-by: Name <email@example.com>

Types:

• feat: New feature (skill, command, hook)
• fix: Bug fix
• docs: Documentation only
• refactor: Code refactoring (no behavior change)
• test: Adding tests
• chore: Maintenance (dependencies, build)

Examples:

feat(skill): Add /jaan-to:qa-test-cases skill

Generate BDD test cases from PRD acceptance criteria.

- Given/When/Then format
- Happy path + edge cases + errors
- Output to jaan-to/outputs/qa/

5. Push and Create PR​

git push origin feature/your-skill-name

Then create a PR on GitHub with:

• Title: Same as commit message first line
• Description:
  • What changed?
  • Why was this change needed?
  • How was it tested?
• Screenshots: If UI/output changes
• Related Issues: Link to issues this PR addresses

For PRs targeting dev, CI automatically builds and uploads both dist artifacts:

• jaan-to-claude-pr-<number>
• jaan-to-codex-pr-<number>

Use .github/pull_request_template.md and complete the dual-runtime checklist before requesting review.

Release Process​

Releases are managed by maintainers. If you're interested in the process:

Versioning​

jaan.to follows Semantic Versioning:

• Major (v2.0.0): Breaking changes
• Minor (v1.1.0): New features (backward compatible)
• Patch (v1.0.1): Bug fixes

Both dev and main use the same X.Y.Z format (e.g., 3.15.0). No -dev suffix.

Release Checklist (Maintainers Only)​

Automated Approach (Recommended):

Use the /jaan-release skill to automate validation, documentation sync, version bump, and PR creation:

# From dev branch (ensure working tree is clean)
/jaan-release

This skill automatically:

1. ✅ Runs 24 validation checks (compliance + plugin standards)
2. ✅ Syncs documentation (roadmap, docs, website, CHANGELOG)
3. ✅ Bumps version atomically across 4 files
4. ✅ Creates PR (dev → main) and waits for CI
5. ⏸️ Stops for human review and merge approval

After skill creates PR:

1. Review and merge PR via GitHub UI
2. Follow post-merge steps (detailed in PR description):
   • Tag release on main
   • Create GitHub release
   • Sync dev branch
   • Bump dev to next version
   • Acknowledge closed issues

Manual Approach (If /jaan-release unavailable):

1. Ensure version and CHANGELOG are ready on dev:

   • Version should already be bumped in all 3 places via ./scripts/bump-version.sh X.Y.Z
   • CHANGELOG.md should have an entry for the version

2. Create PR: dev → main

   • CI checks: all 3 versions match, CHANGELOG entry exists
   • Requires review and approval

3. After merge, tag and push:

   git checkout main
   git pull origin main
   git tag v3.15.0
   git push origin main --tags
   

4. Sync dev back from main:

   git checkout dev
   git merge main
   git push origin dev
   

5. Bump dev to next version (for next release cycle):

   ./scripts/bump-version.sh 3.16.0
   git commit -m "chore: bump version to 3.16.0"
   git push origin dev
   

6. Verify installation works:

   /plugin uninstall jaan-to
   /plugin marketplace add parhumm/jaan-to
   /plugin install jaan-to
   

   Confirm skills appear with /jaan-to:pm-prd-write --help or similar.

IMPORTANT: Version bump, CHANGELOG entry, and git tag are inseparable. Never do one without the others.

See also:

• Validation Architecture - How validation works
• CI Workflows - What CI checks run
• /jaan-release skill - Full skill documentation (LOCAL)

Questions?​

• Documentation: docs/README.md
• Skills Reference: docs/skills/README.md
• Creating Skills: docs/extending/create-skill.md
• GitHub Issues: github.com/parhumm/jaan-to/issues

Thank you for contributing!

Give soul to your workflow.