npm package: @oneplan/claude-helpers
Description: OnePlan development tools and CLI helpers
Author: OnePlan Team
Latest version: 1.0.2

# @oneplan/claude-helpers

OnePlan development tools and CLI helpers for streamlined workflow.

## Installation

### Local Development (for testing)
```bash
cd ~/oneplan-frontend-agent
npm install -D file:../claude-helpers
```

### From NPM Registry (when published)
```bash
npm install -D @oneplan/claude-helpers
```

## Commands

### 1. `oneplan-ticket` - Setup Ticket Environment

Sets up development environment for a Jira ticket:
- Creates git branch from `release/1.0.1`
- Generates `TICKET_CONTEXT.md` with ticket template

**Usage:**
```bash
npx oneplan-ticket OP-1234
```

**Output:**
```
🎫 Setting up ticket OP-1234...
1️⃣  Checking out release/1.0.1...
2️⃣  Pulling latest changes...
3️⃣  Creating branch feat/OP-1234...
4️⃣  Generating TICKET_CONTEXT.md...

✅ Setup complete!
📝 TICKET_CONTEXT.md created
🌿 Branch: feat/OP-1234
```

---

### 2. `oneplan-quality` - Run Quality Gates

Executes all quality gates:
- ✅ TypeScript compilation check (`tsc --noEmit`)
- ✅ ESLint validation
- ✅ Unit tests

**Usage:**
```bash
npx oneplan-quality
```

**Output:**
```
🔍 Running OnePlan Quality Gates...

1️⃣  TypeScript Compilation Check...
✅ TypeScript: PASS

2️⃣  ESLint Validation...
✅ ESLint: PASS

3️⃣  Unit Tests...
✅ Tests: PASS

📊 Quality Gates Summary:
────────────────────────────────────────
TypeScript           ✅ PASS
ESLint               ✅ PASS
Tests                ✅ PASS
────────────────────────────────────────

✅ All quality gates PASSED!
```

---

### 3. `oneplan-pr` - Prepare Pull Request

Prepares and pushes branch for PR creation:
- Checks for uncommitted changes
- Pushes to remote
- Provides PR template

**Usage:**
```bash
npx oneplan-pr OP-1234
```

**Output:**
```
📋 Preparing PR for OP-1234...
1️⃣  Current branch: feat/OP-1234
2️⃣  Checking for uncommitted changes...
3️⃣  Pushing to remote...
4️⃣  Creating PR...

✅ Branch pushed successfully!

📝 Create PR manually with this template:
Title: OP-1234: [Add title here]
🔗 Base branch: release/1.0.1
🔗 Compare branch: feat/OP-1234
```

---

## Integration with package.json

Add shortcuts to your project's `package.json`:

```json
{
  "scripts": {
    "ticket": "oneplan-ticket",
    "quality": "oneplan-quality",
    "pr": "oneplan-pr"
  }
}
```

Then use:
```bash
npm run ticket OP-1234
npm run quality
npm run pr OP-1234
```

---

## Workflow Example

### Complete ticket workflow:

```bash
# 1. Setup ticket
npm run ticket OP-1234

# 2. Open Claude Code
npx claude

# 3. Work on ticket with this prompt:
# "Trabaja en OP-1234 usando TICKET_CONTEXT.md.
#  Protocolo: plan → code → quality → commit"

# 4. Run quality gates (MANDATORY before commit)
npm run quality

# 5. Commit if passing
git add .
git commit -m "feat(OP-1234): implement budget summary" --no-verify

# 6. Push and create PR
npm run pr OP-1234
```

---

## Features

✅ **Zero Configuration** - Works out of the box
✅ **Git Workflow** - Enforces `release/1.0.1` base branch
✅ **Quality Gates** - Automated TypeScript + ESLint + Tests
✅ **Conventional Commits** - Enforces ticket ID in commits
✅ **PR Templates** - Standardized PR format

---

## Requirements

- Node.js >= 18.0.0
- Git configured
- npm or yarn
- Project with:
  - `npm run lint` (ESLint)
  - `npm test` (Jest/Vitest)
  - TypeScript configured

---

## What This Package Does NOT Include

❌ Hooks (user-specific configuration)
❌ Skills (specialized development patterns)
❌ Agents (AI assistant configurations)
❌ Private instructions or protocols

This package contains **only** pure CLI executables for team workflow standardization.

---

## Support

For issues or questions:
- Check `CLAUDE.md` in your project for workflow documentation
- Contact tech lead for architecture questions
- Contact DevOps for environment setup

---

## License

MIT © OnePlan Team

---

**Version:** 1.0.0
**Last Updated:** 2026-01-17