Agent Skills: Base Skill - Universal Patterns

Base Skill - Universal Patterns

Core Principle

Complexity is the enemy. Every line of code is a liability. The goal is software simple enough that any engineer (or AI) can understand the entire system in one session.

Simplicity Rules (STRICTLY ENFORCED)

CRITICAL: These limits are non-negotiable. Claude MUST check and enforce these limits for EVERY file created or modified.

Function Level

• Maximum 20 lines per function - if longer, decompose IMMEDIATELY
• Maximum 3 parameters per function - if more, use an options object or decompose
• Maximum 2 levels of nesting - flatten with early returns or extract functions
• Single responsibility - each function does exactly one thing
• Descriptive names over comments - if you need a comment to explain what, rename it

File Level

• Maximum 200 lines per file - if longer, split by responsibility BEFORE continuing
• Maximum 10 functions per file - keeps cognitive load manageable
• One export focus per file - a file should have one primary purpose

Module Level

• Maximum 3 levels of directory nesting - flat is better than nested
• Clear boundaries - each module has a single public interface
• No circular dependencies - ever

Enforcement Protocol

Before completing ANY file:

1. Count total lines - if > 200, STOP and split
2. Count functions - if > 10, STOP and split
3. Check each function length - if any > 20 lines, STOP and decompose
4. Check parameter counts - if any > 3, STOP and refactor

If limits are exceeded during development:

⚠️ FILE SIZE VIOLATION DETECTED

[filename] has [X] lines (limit: 200)

Splitting into:
- [filename-a].ts - [responsibility A]
- [filename-b].ts - [responsibility B]

Never defer refactoring. Fix violations immediately, not "later".

Architectural Patterns

Functional Core, Imperative Shell

• Pure functions for business logic - no side effects, deterministic
• Side effects only at boundaries - API calls, database, file system at edges
• Data in, data out - functions transform data, they don't mutate state

Composition Over Inheritance

• No inheritance deeper than 1 level - prefer interfaces/composition
• Small, composable utilities - build complex from simple
• Dependency injection - pass dependencies, don't import them directly

Error Handling

• Fail fast, fail loud - errors surface immediately
• No silent failures - every error is logged or thrown
• Design APIs where misuse is impossible

Testing Philosophy

• 100% coverage on business logic - the functional core
• Integration tests for boundaries - API endpoints, database operations
• No untested code merges - CI blocks without passing tests
• Test behavior, not implementation - tests survive refactoring
• Each test runs in isolation - no interdependence

Anti-Patterns (Never Do This)

• ❌ Global state
• ❌ Magic numbers/strings - use named constants
• ❌ Deep nesting - flatten or extract
• ❌ Long parameter lists - use objects
• ❌ Comments explaining "what" - code should be self-documenting
• ❌ Dead code - delete it, git remembers
• ❌ Copy-paste duplication - extract to shared function
• ❌ God objects/files - split by responsibility
• ❌ Circular dependencies
• ❌ Premature optimization
• ❌ Large PRs - small, focused changes only
• ❌ Mixing refactoring with features - separate commits

Documentation Structure

Every project must have clear separation between code docs and project specs:

project/
├── docs/                      # Code documentation
│   ├── architecture.md        # System design decisions
│   ├── api.md                 # API reference (if applicable)
│   └── setup.md               # Development setup guide
├── _project_specs/            # Project specifications
│   ├── overview.md            # Project vision and goals
│   ├── features/              # Feature specifications
│   │   ├── feature-a.md
│   │   └── feature-b.md
│   ├── todos/                 # Atomic todos tracking
│   │   ├── active.md          # Current sprint/focus
│   │   ├── backlog.md         # Future work
│   │   └── completed.md       # Done items (for reference)
│   ├── session/               # Session state (see session-management.md)
│   │   ├── current-state.md   # Live session state
│   │   ├── decisions.md       # Key decisions log
│   │   ├── code-landmarks.md  # Important code locations
│   │   └── archive/           # Past session summaries
│   └── prompts/               # LLM prompt specifications (if AI-first)
└── CLAUDE.md                  # Claude instructions (references skills)

What Goes Where

| Location | Content | |----------|---------| | docs/ | Technical documentation, API refs, setup guides | | _project_specs/ | Business logic, features, requirements, todos | | _project_specs/session/ | Session state, decisions, context for resumability | | CLAUDE.md | Claude-specific instructions and skill references |

Atomic Todos

All work is tracked as atomic todos with validation and test criteria.

Todo Format (Required)

## [TODO-001] Short descriptive title

**Status:** pending | in-progress | blocked | done
**Priority:** high | medium | low
**Estimate:** XS | S | M | L | XL

### Description
One paragraph describing what needs to be done.

### Acceptance Criteria
- [ ] Criterion 1 - specific, measurable
- [ ] Criterion 2 - specific, measurable

### Validation
How to verify this is complete:
- Manual: [steps to manually test]
- Automated: [test file/command that validates this]

### Test Cases
| Input | Expected Output | Notes |
|-------|-----------------|-------|
| ... | ... | ... |

### Dependencies
- Depends on: [TODO-xxx] (if any)
- Blocks: [TODO-yyy] (if any)

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| RED | `[test command]` | - | - |
| GREEN | `[test command]` | - | - |
| VALIDATE | `[lint && typecheck && test --coverage]` | - | - |
| COMPLETE | Moved to completed.md | - | - |

Todo Rules

1. Atomic - Each todo is a single, completable unit of work
2. Testable - Every todo has validation criteria and test cases
3. Sized - If larger than "M", break it down further
4. Independent - Minimize dependencies between todos
5. Tracked - Move between active.md → completed.md when done

Todo Execution Workflow (TDD - Mandatory)

Every todo MUST follow this exact workflow. No exceptions.

┌─────────────────────────────────────────────────────────────┐
│  1. RED: Write Tests First                                  │
│     └─ Create test file(s) based on Test Cases table        │
│     └─ Tests should cover all acceptance criteria           │
│     └─ Run tests → ALL MUST FAIL (proves tests are valid)   │
├─────────────────────────────────────────────────────────────┤
│  2. GREEN: Implement the Feature                            │
│     └─ Write minimum code to make tests pass                │
│     └─ Follow simplicity rules (20 lines/function, etc.)    │
│     └─ Run tests → ALL MUST PASS                            │
├─────────────────────────────────────────────────────────────┤
│  3. VALIDATE: Quality Gates                                 │
│     └─ Run linter (auto-fix if possible)                    │
│     └─ Run type checker (tsc/mypy/pyright)                  │
│     └─ Run full test suite with coverage                    │
│     └─ Verify coverage threshold (≥80%)                     │
├─────────────────────────────────────────────────────────────┤
│  4. COMPLETE: Mark Done                                     │
│     └─ Only after ALL validations pass                      │
│     └─ Move todo to completed.md                            │
│     └─ Checkpoint session state                             │
└─────────────────────────────────────────────────────────────┘

Execution Commands by Stack

Node.js/TypeScript:

# 1. RED - Run tests (expect failures)
npm test -- --grep "todo-description"

# 2. GREEN - Run tests (expect pass)
npm test -- --grep "todo-description"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage

Python:

# 1. RED - Run tests (expect failures)
pytest -k "todo_description" -v

# 2. GREEN - Run tests (expect pass)
pytest -k "todo_description" -v

# 3. VALIDATE - Full quality check
ruff check . && mypy . && pytest --cov --cov-fail-under=80

React/Next.js:

# 1. RED - Run tests (expect failures)
npm test -- --testPathPattern="ComponentName"

# 2. GREEN - Run tests (expect pass)
npm test -- --testPathPattern="ComponentName"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage --watchAll=false

Blocking Conditions

NEVER mark a todo as complete if:

• ❌ Tests were not written first (skipped RED phase)
• ❌ Tests did not fail initially (invalid tests)
• ❌ Any test is failing
• ❌ Linter has errors (warnings may be acceptable)
• ❌ Type checker has errors
• ❌ Coverage dropped below threshold

If blocked by failures:

## [TODO-042] - BLOCKED

**Blocking Reason:** [Lint error in X / Test failure in Y / Coverage at 75%]
**Action Required:** [Specific fix needed]

Bug Fix Workflow (TDD - Mandatory)

When a user reports a bug, NEVER jump to fixing it directly.

┌─────────────────────────────────────────────────────────────┐
│  1. DIAGNOSE: Identify the Test Gap                         │
│     └─ Run existing tests - do any fail?                    │
│     └─ If tests pass but bug exists → tests are incomplete  │
│     └─ Document: "Test gap: [what was missed]"              │
├─────────────────────────────────────────────────────────────┤
│  2. RED: Write a Failing Test for the Bug                   │
│     └─ Create test that reproduces the exact bug            │
│     └─ Test should FAIL with current code                   │
│     └─ This proves the test catches the bug                 │
├─────────────────────────────────────────────────────────────┤
│  3. GREEN: Fix the Bug                                      │
│     └─ Write minimum code to make the test pass             │
│     └─ Run test → must PASS now                             │
├─────────────────────────────────────────────────────────────┤
│  4. VALIDATE: Full Quality Check                            │
│     └─ Run ALL tests (not just the new one)                 │
│     └─ Run linter and type checker                          │
│     └─ Verify no regression in coverage                     │
└─────────────────────────────────────────────────────────────┘

Bug Report Todo Format

## [BUG-001] Short description of the bug

**Status:** pending
**Priority:** high
**Reported:** [how user reported it / reproduction steps]

### Bug Description
What is happening vs. what should happen.

### Reproduction Steps
1. Step one
2. Step two
3. Observe: [incorrect behavior]
4. Expected: [correct behavior]

### Test Gap Analysis
- Existing test coverage: [list relevant test files]
- Gap identified: [what the tests missed]
- New test needed: [describe the test to add]

### Test Cases for Bug
| Input | Current (Bug) | Expected (Fixed) |
|-------|---------------|------------------|
| ... | ... | ... |

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| DIAGNOSE | `npm test` | All pass (gap!) | - |
| RED | `npm test -- --grep "bug description"` | 1 test failed ✓ | - |
| GREEN | `npm test -- --grep "bug description"` | 1 test passed ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | Pass ✓ | - |

Bug Fix Anti-Patterns

• ❌ Fixing without a test - Bug will likely return
• ❌ Writing test after fix - Can't prove test catches the bug
• ❌ Skipping test gap analysis - Misses why tests didn't catch it
• ❌ Only testing the fix - Must run full test suite for regressions

Example Atomic Todo

## [TODO-042] Add email validation to signup form

**Status:** pending
**Priority:** high
**Estimate:** S

### Description
Validate email format on the signup form before submission. Show inline error if invalid.

### Acceptance Criteria
- [ ] Email field shows error for invalid format
- [ ] Error clears when user fixes the email
- [ ] Form cannot submit with invalid email
- [ ] Valid emails pass through without error

### Validation
- Manual: Enter "notanemail" in signup form, verify error appears
- Automated: `npm test -- --grep "email validation"`

### Test Cases
| Input | Expected Output | Notes |
|-------|-----------------|-------|
| user@example.com | Valid, no error | Standard email |
| user@sub.example.com | Valid, no error | Subdomain |
| notanemail | Invalid, show error | No @ symbol |
| user@ | Invalid, show error | No domain |
| @example.com | Invalid, show error | No local part |

### Dependencies
- Depends on: [TODO-041] Signup form component
- Blocks: [TODO-045] Signup flow integration test

### TDD Execution Log
| Phase | Command | Result | Timestamp |
|-------|---------|--------|-----------|
| RED | `npm test -- --grep "email validation"` | 5 tests failed ✓ | - |
| GREEN | `npm test -- --grep "email validation"` | 5 tests passed ✓ | - |
| VALIDATE | `npm run lint && npm run typecheck && npm test -- --coverage` | Pass, 84% coverage ✓ | - |
| COMPLETE | Moved to completed.md | ✓ | - |

Credentials Management (Non-Negotiable)

When a project needs API keys, always ask the user for their centralized access file first.

Workflow

1. Ask: "Do you have an access keys file? (e.g., ~/Documents/Access.txt)"
2. Read and parse the file for known key patterns
3. Validate keys are working
4. Create project .env with found keys
5. Report missing keys and where to get them

Key Patterns to Detect

| Service | Pattern | Env Variable | |---------|---------|--------------| | OpenAI | sk-proj-* | OPENAI_API_KEY | | Claude | sk-ant-* | ANTHROPIC_API_KEY | | Render | rnd_* | RENDER_API_KEY | | Replicate | r8_* | REPLICATE_API_TOKEN | | Reddit | client_id + secret | REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET |

See credentials.md for full parsing logic and validation commands.

Security (Non-Negotiable)

Every project must meet these security requirements. See security.md skill for detailed patterns.

Essential Security Checks

1. No secrets in code - Use environment variables, never commit secrets
2. .env in .gitignore - Always, no exceptions
3. No secrets in client-exposed env vars - Never use VITE_*, NEXT_PUBLIC_* for secrets
4. Validate all input - Use Zod/Pydantic at API boundaries
5. Parameterized queries only - No string concatenation for SQL
6. Hash passwords properly - bcrypt with 12+ rounds
7. Dependency scanning - npm audit / safety check must pass

Required Files

• .gitignore with secrets patterns
• .env.example with all required vars (no values)
• scripts/security-check.sh for pre-commit validation

Security in CI

Every PR must pass:

• Secret scanning (detect-secrets / trufflehog)
• Dependency audit (npm audit / safety)
• Static analysis (CodeQL)

Quality Gates (Non-Negotiable)

Coverage Threshold

• Minimum 80% code coverage - CI must fail below this
• Business logic (core/) should aim for 100%
• Integration tests cover boundaries

Pre-Commit Hooks

All projects must have pre-commit hooks that run:

1. Linting (auto-fix where possible)
2. Type checking
3. Tests (at minimum, affected tests)

This catches issues before they hit CI, saving time and keeping the main branch clean.

Session Management (Non-Negotiable)

Maintain context for resumability. See session-management.md for full details.

Core Rule: Checkpoint at Natural Breakpoints

After completing any task, ask:

1. Decision made? → Log to _project_specs/session/decisions.md
2. >10 tool calls? → Full checkpoint to current-state.md
3. Major feature done? → Archive to session/archive/
4. Otherwise → Quick update to current-state.md

Session Start

1. Read _project_specs/session/current-state.md
2. Check _project_specs/todos/active.md
3. Continue from documented "Next Steps"

Session End

1. Archive current session
2. Update current-state.md with handoff notes
3. Ensure next steps are specific and actionable

Response Format

When implementing features (following TDD):

1. Clarify requirements if ambiguous
2. Propose structure - outline before code
3. Write tests FIRST - based on test cases table (RED phase)
4. Run tests to verify they fail - proves tests are valid
5. Implement minimum code to make tests pass (GREEN phase)
6. Run full validation - lint, typecheck, coverage (VALIDATE phase)
7. Flag complexity - warn if approaching limits
8. Checkpoint after completing - update session state, log TDD execution

TDD is non-negotiable. Tests must exist and fail before any implementation begins.

When you notice code violating these rules, stop and refactor before continuing.

Automatic Iterative Mode (Ralph Wiggum)

For any non-trivial task, Claude MUST automatically use iterative TDD loops.

When to Auto-Invoke Ralph Loop

| Task Type | Action | |-----------|--------| | New feature (any size) | /ralph-loop with TDD template | | Bug fix | /ralph-loop with bug fix template | | Refactoring | /ralph-loop with refactor template | | API development | /ralph-loop with API template | | Simple question/explanation | Normal response (no loop) | | One-line fix (typo, etc.) | Normal response (no loop) |

Auto-Transform User Requests

When user says something like:

• "Add email validation"
• "Fix the login bug"
• "Build a REST API for todos"
• "Refactor the auth module"

Claude MUST automatically:

1. Extract requirements from the request
2. Define completion criteria (tests passing, lint clean, etc.)
3. Structure as Ralph prompt with TDD workflow
4. Invoke /ralph-loop with appropriate --max-iterations and --completion-promise

Auto-Transformation Example

User says:

"Add a forgot password feature"

Claude automatically invokes:

/ralph-loop "
## Task: Add forgot password feature

### Requirements (extracted from user request)
- User can request password reset via email
- Reset link sent to registered email
- Link expires after 24 hours
- User can set new password via link

### TDD Workflow
1. Write failing tests for each requirement
2. Verify tests FAIL (RED)
3. Implement feature
4. Verify tests PASS (GREEN)
5. Run lint + typecheck
6. Repeat if failures

### Completion Criteria
- [ ] All tests passing
- [ ] Coverage >= 80%
- [ ] Lint clean
- [ ] Security review (no token in URL params, etc.)

### Exit Condition
<promise>FORGOT PASSWORD COMPLETE</promise>
" --completion-promise "FORGOT PASSWORD COMPLETE" --max-iterations 25

Default Settings

| Setting | Default | Rationale | |---------|---------|-----------| | --max-iterations | 20-30 | Safety net, adjust by complexity | | --completion-promise | Always set | Based on task (e.g., "TESTS PASSING") | | TDD workflow | Always included | Non-negotiable |

Opt-Out

User can opt out of automatic Ralph loops by saying:

• "Just explain..." (explanation only)
• "Quick fix for..." (one-liner)
• "Don't loop..." (explicit opt-out)
• "Help me understand..." (learning/discussion)