This Claude skill establishes a robust framework for development workflow standards and code quality requirements. It optimizes the software development lifecycle (SDLC) by defining strict pre-commit checks, project initialization patterns, and agent-assisted task decomposition strategies. By integrating these standards, developers and AI agents can ensure consistent code quality, efficient script organization, and reliable project management.

When should I use smith-dev?

smith-dev is useful in the following scenarios: • Project Initialization: Automatically setting up new repositories with standardized directory structures and package management configurations for Python (Poetry/uv) or Frontend (pnpm). • Automated Quality Gates: Enforcing mandatory linting, formatting, and testing protocols to ensure that only high-quality, verified code is committed to version control. • Agent Task Decomposition: Guiding AI agents to break down complex development goals into 3-5 verifiable milestones, preventing context drift and ensuring focused implementation. • Script Lifecycle Management: Organizing temporary debugging scripts and providing a clear migration path for promoting reusable utilities into production-ready CLI tools. • Pre-PR Validation: Streamlining the pull request process by requiring self-reviews, branch synchronization, and comprehensive quality checks before submission.

name	smith-dev
description	Development workflow standards and code quality requirements. Use when initializing projects, running quality checks, or managing agent tasks. Covers pre-commit checks, task decomposition, and script organization patterns.

Development Workflow Standards

Scope: Development workflow standards and code quality requirements
Load if: Initializing a new project
Prerequisites: @smith-principles/SKILL.md, @smith-standards/SKILL.md

This document defines development workflow standards and code quality requirements.

CRITICAL (Primacy Zone)

Committing without running formatters and linters
Committing without running tests
Creating PRs with failing quality checks
Having more than ONE task in_progress simultaneously

Code Quality (MANDATORY)

MUST run formatters and linters before commits
MUST run tests before commits
MUST fix all linting errors

Language-specific commands:

Python: See @smith-python/SKILL.md#action-recency-zone (supports Poetry and uv)
TypeScript/Frontend: See @smith-typescript/SKILL.md

Agent-Assisted Development

For AI agent workflows: See @smith-guidance/SKILL.md for comprehensive patterns:

Exploration workflow (Read → Ask → Propose → Review → Implement)
Debugging workflow (Reproduce → Analyze → Hypothesize → Test → Verify)
AGENTS.md optimization for prompt caching
Constitutional AI principles (HHH framework)

Agent Task Decomposition

Sweet spot: 3-5 high-level milestones, not micro-steps

Tasks MUST focus on logical phases, be independently verifiable
Exactly ONE task in_progress at any time
Mark complete only after tests pass and changes committed
Use git commits + todos for session bridging

Task states: pending → in_progress → completed

Dependencies: Note in task description (e.g., "depends on #1")

Pre-PR Quality Gates

Before creating a pull request:

MUST run all formatters and linters (see language-specific skills)
MUST run all tests
MUST ensure branch is up-to-date with base branch
MUST review your own changes first (git diff)

See: @smith-gh-pr/SKILL.md - Pull request creation workflow See: @smith-gh-cli/SKILL.md - GitHub-specific PR commands

Package Management

Python:

Use package manager for dependency management (Poetry or uv)
Local .venv directories (project-local virtual environments)
Lock files: poetry.lock or uv.lock (commit to version control)

Frontend:

Use pnpm for dependency management
Lock files: pnpm-lock.yaml (commit to version control)

Script Organization

Directory Structure

Temporary analysis: debug_scripts/

Quick explorations and debugging
NOT committed to production
Output files in debug_scripts/outputs/

Production tools: cli/ or cli/prompt_engineering/

Version-controlled utilities
Team-accessible tools
Production-ready quality

Script Migration

Migrate from debug_scripts/ → cli/ when:

Used by multiple team members
Has general applicability beyond debugging
Provides reusable functionality
Requires version control

Migration process:

Copy to cli/ with enhanced functionality
Update documentation references
Remove from debug_scripts/ after validation
Update tool documentation
Inform team

Output Organization

Directory: debug_scripts/outputs/ (add to .gitignore) Naming: [purpose]_[id]_[timestamp].json

Logging and Observability

Logging levels:

DEBUG: Only when actively debugging
WARNING: Default for external libraries (httpx, openai, fastapi)
INFO: Application-level events

Configuration:

Centralized controls in project documentation
Test logging: Configure via pytest.ini and pyproject.toml

Ralph Loop Integration

Milestones = Ralph iterations: Each phase boundary triggers quality gates.

See @smith-ralph/SKILL.md for full patterns.

@smith-principles/SKILL.md - Fundamental coding principles
@smith-standards/SKILL.md - Universal code standards
@smith-python/SKILL.md - Python-specific patterns
@smith-tests/SKILL.md - Testing standards
@smith-git/SKILL.md - Version control workflow
@smith-gh-cli/SKILL.md - GitHub CLI operations
@smith-style/SKILL.md - Naming conventions

ACTION (Recency Zone)

Before committing:

Run formatters, linters, and tests (see @smith-python/SKILL.md or @smith-typescript/SKILL.md)

Task management:

One task in_progress at a time
Mark complete only after tests pass
Commit frequently for session recovery

smith-dev

When & Why to Use This Skill

Use Cases