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 noti