# Project Workflow

> Development workflow and quality gates for the Bun + TypeScript stack. **ALWAYS use before commits** to ensure quality gates are met. Also use when starting development or when user asks about workflow process. Examples - "before commit", "quality gates", "workflow checklist", "bun commands", "pre-commit checks".

- Skill: `marcioaltoe/project-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add marcioaltoe/project-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marcioaltoe/project-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: marcioaltoe (https://skillmd.com/u/marcioaltoe)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/marcioaltoe/project-workflow

---


You are an expert in guiding developers through the project's development workflow and quality gates. You ensure all necessary steps are executed before committing code.

**For complete project rules and standards, see CLAUDE.md (global instructions)**

## When to Engage

You should proactively assist:

- **Before committing code** (most important)
- When user asks about workflow or process
- When setting up quality gates
- When troubleshooting Bun-specific issues

## Pre-Commit Checklist

**MANDATORY - Execute in this order:**

```bash
# Step 1: Update barrel files (if files were added/moved/deleted)
bun run craft

# Step 2: Format code
bun run format

# Step 3: Lint code
bun run lint

# Step 4: Type check
bun run type-check

# Step 5: Run tests
bun run test
```

**Or run all at once:**

```bash
bun run quality  # Executes all 5 steps
```

**Checklist:**

- [ ] Files added/moved/deleted? Run `bun run craft`
- [ ] All tests passing? (`bun run test` - green)
- [ ] No TypeScript errors? (`bun run type-check` - clean)
- [ ] No linting errors? (`bun run lint` - clean)
- [ ] Code formatted? (`bun run format` - applied)
- [ ] Committed to feature branch? (not main/dev)
- [ ] Commit message follows conventions?

**For complete TypeScript type safety rules (type guards), see `typescript-type-safety` skill**

## Bun-Specific Commands

### Testing Commands

**CRITICAL - NEVER use:**

```bash
bun test  # ❌ WRONG - May not work correctly
```

**ALWAYS use:**

```bash
bun run test  # ✅ CORRECT - Uses package.json script
```

### Barrel Files

**ALWAYS run after creating/moving/deleting files:**

```bash
bun run craft
```

This updates barrel files (index.ts exports) for clean imports.

**When to run:**

- After creating new files
- After moving/renaming files
- After deleting files
- Before committing changes

## Bun Runtime APIs

**Prefer Bun APIs over Node.js:**

```typescript
// ✅ Password hashing
const hashedPassword = await Bun.password.hash(password, {
  algorithm: "bcrypt",
  cost: 10,
});

// ✅ File operations
const file = Bun.file("./config.json");
const config = await file.json();

// ✅ UUID v7
const id = Bun.randomUUIDv7();

// ✅ SQLite
import { Database } from "bun:sqlite";
const db = new Database("mydb.sqlite");

// ✅ HTTP server
import { serve } from "bun";
serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});
```

## Quality Gates Execution Order

**Why this order matters:**

1. **craft** - Ensures imports are correct before other checks
2. **format** - Auto-fixes formatting issues
3. **lint** - Catches code quality issues
4. **type-check** - Validates TypeScript correctness
5. **test** - Ensures functionality works

**Each step depends on the previous one passing.**

## Common Workflow Mistakes

**Mistakes to avoid:**

1. ❌ Using `bun test` instead of `bun run test`
2. ❌ Forgetting `bun run craft` after file operations
3. ❌ Committing with TypeScript errors
4. ❌ Skipping quality gates
5. ❌ Running quality gates out of order
6. ❌ Committing directly to main/dev branches
7. ❌ Using Node.js APIs instead of Bun APIs
8. ❌ Relative imports instead of barrel files

## Quick Reference

**Before every commit:**

```bash
bun run quality    # Run all quality gates
git status         # Verify changes
git add .          # Stage changes
git commit -m "feat(scope): description"  # Commit with convention
```

**Starting new feature:**

```bash
git checkout dev
git pull origin dev
git checkout -b feature/feature-name
# ... make changes ...
bun run quality
git commit -m "feat: add feature"
```

**File operations workflow:**

```bash
# Create new files
# ...
bun run craft      # Update barrel files
bun run quality    # Run quality gates
git commit
```

## Remember

- **Quality gates are mandatory** - Not optional
- **Bun commands are specific** - Use `bun run test`, not `bun test`
- **Order matters** - Follow the quality gates sequence
- **Barrel files are critical** - Run `bun run craft` after file changes
- **Check CLAUDE.md** - For complete project rules and standards