Warping

Warping Framework

A layered framework for AI-assisted development with consistent standards and workflows.

When This Skill Activates

This skill automatically loads when you:

• Start work in a warping-enabled project (has ./warping/ directory)
• Reference warping, project standards, or coding conventions
• Run tests, make commits, or perform quality checks
• Ask about project structure, workflows, or best practices

Core Principle: Rule Precedence

Warping uses hierarchical rules where more specific overrides general:

user.md          ← HIGHEST precedence (personal preferences)
  ↓
project.md       ← Project-specific rules
  ↓
{language}.md    ← Language standards (python.md, go.md, typescript.md, cpp.md)
  ↓
{tool}.md        ← Tool guidelines (taskfile.md, git.md)
  ↓
main.md          ← General AI behavior
  ↓
specification.md ← LOWEST precedence (requirements)

IMPORTANT: If user.md says one thing and python.md says another, user.md ALWAYS wins.

File Reading Strategy (Lazy Loading)

DO NOT read all warping files at once. Read only what you need:

1. Always start with: ./warping/main.md (general guidelines)
2. Check for: ./warping/core/user.md (personal overrides - highest precedence)
3. Check for: ./warping/core/project.md (project-specific rules)
4. Then read language-specific only if working with that language:
   • ./warping/languages/python.md
   • ./warping/languages/go.md
   • ./warping/languages/typescript.md
   • ./warping/languages/cpp.md
5. Read tool files only when using that tool:
   • ./warping/tools/taskfile.md (when running tasks)
   • ./warping/scm/git.md (when using git)
   • ./warping/scm/github.md (when using GitHub)

Task-Centric Workflow

Warping projects use Taskfile as the universal task runner.

Discovery

task --list        # See all available tasks
task               # Same as task --list

Common Tasks

task check         # Pre-commit checks (fmt, lint, test, coverage)
task test          # Run tests
task test:coverage # Run with coverage
task fmt           # Format code
task lint          # Lint code
task build         # Build project
task clean         # Clean artifacts

CRITICAL: Before commits, ALWAYS run task check. Never claim checks passed without running them.

Test-Driven Development (TDD)

Warping embraces TDD by default:

1. Write test first - Define expected behavior
2. Watch it fail - Confirm test fails correctly
3. Implement - Write minimal code to pass
4. Refactor - Improve while keeping tests green
5. Repeat - Build incrementally

Coverage Requirements:

• Default: ≥85% coverage (overall + per-module)
• Check project.md for project-specific thresholds
• Never claim coverage passes without running task test:coverage

Spec-Driven Development (SDD)

For new features or projects:

1. Build PRD.md - Run warping.sh spec to create Product Requirements Document
2. AI Interview - Answer focused questions to clarify requirements
3. PRD.md Review - Let user review/change PRD.md if they want
4. Generate SPECIFICATION.md - use PRD.md + Warping rules to build a complete spec with phases, dependencies, and tasks
5. SPECIFICATION.md review -- Let user review/change SPECIFICATION.md if they want
6. Implement - Build according to spec, following all applicable warping rules

Quality Standards

Before Every Commit

task check  # MUST run this

This typically includes:

• Code formatting
• Linting
• Type checking
• Tests with coverage
• Any project-specific checks

Conventional Commits

ALL commits must follow https://www.conventionalcommits.org/en/v1.0.0/:

feat: add new feature
fix: resolve bug
docs: update documentation
chore: routine tasks
test: add/update tests
refactor: code restructuring

File Naming

• Use hyphens in filenames, not underscores
• Example: user-service.py NOT user_service.py
• Exception: Language conventions (Python modules can use underscores in code)

Secrets Management

• Store secrets in secrets/ directory
• Provide .example templates
• Never commit actual secrets
• Use environment variables in code

Language-Specific Standards

Python

• Testing: pytest, ≥85% coverage
• Style: ruff, black, isort (PEP 8)
• Types: mypy strict mode
• Docs: PEP 257 docstrings

Go

• Testing: Testify, ≥85% coverage
• Docs: go.dev/doc/comment
• Patterns: table-driven tests, interface design

TypeScript

• Testing: Vitest/Jest, ≥85% coverage
• Style: ESLint, Prettier
• Types: strict mode, no any

C++

• Testing: Catch2/GoogleTest, ≥85% coverage
• Standard: C++20/23
• Style: clang-format, clang-tidy

New Project Workflow

When user says "start a new project with warping", "use warping to build X", or similar, follow this complete workflow:

Step 1: Initialize Warping Structure

./warping.sh init

• Creates ./warping/ directory with framework files
• Sets up secrets/ directory
• Creates basic Taskfile.yml
• Adds .gitignore for secrets

Step 2: User Configuration (First Time Only)

Check if ./warping/core/user.md exists. If not:

./warping.sh bootstrap

• Prompts for user name
• Sets default coverage threshold
• Configures primary languages
• Creates personalized user.md

Step 3: Project Configuration

./warping.sh project

• Prompts for project name
• Selects project type (CLI, TUI, REST API, Web App, Library, Other)
• Chooses primary language
• Sets coverage threshold
• Creates project.md with standards

Step 4: Specification-Driven Development

./warping.sh spec

This launches the full SDD workflow:

a) Generate PRD.md:

• Prompts for project name, description, and initial features
• Creates PRD.md with structured template
• Displays full path to PRD.md

b) Conduct AI Interview:

• Read the PRD.md thoroughly
• Ask focused, non-trivial questions to clarify:
  • Missing decisions and edge cases
  • Implementation details and architecture
  • UX considerations and constraints
  • Dependencies and tradeoffs
• Each question should have numbered options plus "other"
• Continue until ambiguity is minimized

c) User Review of PRD:

• Let user review/edit PRD.md if they want
• Wait for confirmation before proceeding

d) Generate SPECIFICATION.md:

• Use PRD.md + warping rules to create complete implementation spec
• Include clear phases, subphases, and tasks
• Map dependencies (what blocks what)
• Identify parallel work opportunities
• NO code in specification - just the plan

e) User Review of Specification:

• Let user review/edit SPECIFICATION.md if they want
• Wait for confirmation before implementation

f) Begin Implementation:

• Follow the SPECIFICATION.md plan
• Apply all warping rules (TDD, quality standards, task-centric)
• Maintain ≥85% coverage
• Run task check before each commit
• Use Conventional Commits format

Step 5: Development Cycle

• Write tests first (TDD)
• Implement features incrementally
• Run task check frequently
• Commit with proper format
• Push changes

Project Initialization (Quick Reference)

For New Projects (Full Workflow)

Use the "New Project Workflow" above when starting from scratch.

For Existing Warping Projects

1. Check for ./warping/ directory
2. Read ./warping/main.md for general guidelines
3. Read ./warping/core/user.md for user preferences
4. Read ./warping/core/project.md for project rules
5. Run task --list to see available tasks

For New Features in Existing Projects

1. Consider running ./warping.sh spec for complex features
2. Follow SDD process (PRD → Interview → Specification → Implement)
3. Or for simple features, just follow TDD directly

Self-Improvement Mechanism

Warping learns and evolves:

• meta/lessons.md - Patterns learned during development (AI can update)
• meta/ideas.md - Future improvements noticed
• meta/suggestions.md - Project-specific suggestions

When you discover a better pattern or make repeated corrections, consider updating lessons.md.

Safety and Best Practices

Version Control

• Never force-push without explicit permission
• Assume production impact unless stated otherwise
• Prefer small, reversible changes
• Call out risks explicitly

Code Quality

• Run task check before EVERY commit
• Verify tests pass: task test
• Check coverage meets threshold: task test:coverage
• Never claim checks passed without running them

Documentation

• Keep docs in docs/ directory, not project root
• Update docs when changing behavior
• Use RFC2119 notation in technical docs (!, ~, ?, ⊗, ≉)

Working with Warping

First Time in a Project

1. Check for ./warping/ directory
2. Read ./warping/main.md
3. Check ./warping/core/user.md for user preferences
4. Check ./warping/core/project.md for project rules
5. Run task --list to see available tasks

During Development

1. Write tests first (TDD)
2. Implement features
3. Run task check frequently
4. Before commit: ALWAYS task check
5. Use Conventional Commits format
6. Push changes

When Stuck

• Check ./warping/REFERENCES.md for guidance on which files to read
• Review meta/lessons.md for learned patterns
• Consult language-specific files in ./warping/languages/
• Check Taskfile.yml for available commands

Example Workflows

Starting a Feature

# 1. Write test first (TDD)
# 2. Watch it fail
task test

# 3. Implement feature
# 4. Run checks
task check

# 5. Commit
git commit -m "feat: add new feature"

Code Review

# 1. Run quality checks
task check

# 2. Review coverage
task test:coverage

# 3. Check commit format (Conventional Commits)
git log --oneline -n 5

# 4. Suggest improvements → meta/suggestions.md

Bug Fix

# 1. Write failing test that reproduces bug
# 2. Fix code
# 3. Verify test passes
task test

# 4. Run full checks
task check

# 5. Commit
git commit -m "fix: resolve issue with X"

Integration Notes

This SKILL.md follows the AgentSkills specification, making it compatible with multiple AI platforms.

With Claude Code

• This SKILL.md file teaches Claude Code about warping
• Place in ~/.claude/skills/warping/ (personal) or .claude/skills/warping/ (project)
• Claude automatically applies these rules when relevant
• Works in VS Code via Claude Code extension

With clawd.bot

• Compatible with clawd.bot's AgentSkills system
• Place in ~/.clawdbot/skills/warping/ (shared) or <workspace>/skills/warping/ (per-agent)
• Install via ClawdHub: clawdhub sync warping (once published)
• Works across WhatsApp, Telegram, Discord, and other channels
• Requires task binary (specified in metadata)
• Supports macOS and Linux (specified in os field)

With Warp AI

• Upload warping files to Warp Drive
• Create Warp rules referencing warping/*.md files
• Use WARP.md or AGENTS.md in project root

Skill Locations

Claude Code:

• Personal: ~/.claude/skills/warping/SKILL.md
• Project: .claude/skills/warping/SKILL.md

clawd.bot:

• Shared (all agents): ~/.clawdbot/skills/warping/SKILL.md
• Per-agent: <workspace>/skills/warping/SKILL.md
• Via registry: clawdhub sync warping

Warping files: ./warping/*.md (framework files)

Publishing to Registries

Claude Code Skills Marketplace:

• Browse: https://skillsmp.com
• Submit via GitHub repository
• Tag with claude-skills, ai-coding

ClawdHub (clawd.bot):

• Browse: https://clawdhub.com
• Publish: clawdhub publish
• Update: clawdhub publish --version x.y.z

Multi-Platform Benefits

• Same format - Write once, use everywhere
• Consistent standards - Warping rules apply across all AI assistants
• Universal workflows - TDD, SDD, quality checks work in any context
• Shared knowledge - Updates propagate to all platforms

Quick Reference

Remember

1. Lazy load files - Only read what you need
2. User.md is king - Highest precedence always
3. Task-centric - Use task for everything
4. Test first - Write tests before implementation
5. Always check - Run task check before commits
6. Conventional commits - Follow the standard
7. Coverage matters - ≥85% by default
8. Never lie - Don't claim checks passed without running them

For more details, read the specific files in ./warping/ as needed. Start with main.md and follow the precedence hierarchy.