Appendices

def function_name(param1: type, param2: type) -> return_type:
    """One-line description of what this function does."""
    # logic here
    return result

# 1. Write the test first
def test_feature():
    result = my_function(input)
    assert result == expected

# 2. Run: python3 -m pytest (watch it fail — RED)
# 3. Write minimum code to pass
# 4. Run: python3 -m pytest (watch it pass — GREEN)
# 5. Refactor if needed

import json
from pathlib import Path

def load_data(filepath: str) -> list[dict]:
    """Load JSON data from file. Return empty list if file missing."""
    path = Path(filepath)
    if not path.exists():
        return []
    return json.loads(path.read_text())

def save_data(filepath: str, data: list[dict]) -> None:
    """Write data to JSON file with pretty formatting."""
    Path(filepath).write_text(json.dumps(data, indent=2))

# Usage
tasks = load_data("tasks.json")
tasks.append({"id": len(tasks) + 1, "title": "New task", "status": "todo"})
save_data("tasks.json", tasks)

# Common string operations for data cleaning
def clean_and_parse(raw: str) -> dict:
    """Strip whitespace, split on delimiter, return structured data."""
    line = raw.strip()
    parts = line.split(",")
    return {
        "name": parts[0].strip().title(),
        "email": parts[1].strip().lower(),
        "role": parts[2].strip() if len(parts) > 2 else "unknown",
    }

# f-string formatting
summary = f"{task['title']} ({task['status']}) — due {task['due_date']}"

# String methods chain
normalized = user_input.strip().lower().replace(" ", "_")

def test_filter_tasks_by_status():
    tasks = [
        {"id": 1, "title": "Buy milk", "status": "todo"},
        {"id": 2, "title": "Walk dog", "status": "done"},
    ]
    result = filter_tasks(tasks, status="done")
    assert len(result) == 1
    assert result[0]["title"] == "Walk dog"

# Find Python files containing "TODO" and count them
grep -r "TODO" --include="*.py" . | wc -l

# List the 5 largest files in src/
du -sh src/* | sort -rh | head -5

git checkout -b feature/add-tags
# ... make changes ...
git add src/taskforge/models.py tests/test_tags.py
git commit -m "feat: add tag support with filtering"
git checkout main
git merge feature/add-tags

# Set up remote and push
git remote add origin git@github.com:username/taskforge.git
git push -u origin main

# Feature branch workflow with remote
git checkout -b feature/api-endpoints
# ... make changes, commit locally ...
git push -u origin feature/api-endpoints

# Create pull request (using GitHub CLI)
gh pr create --title "Add API endpoints" --body "Implements REST API for tasks"

# After PR review and merge, update local main
git checkout main
git pull origin main
git branch -d feature/api-endpoints

# GET request — retrieve data
curl -s https://httpbin.org/get | python3 -m json.tool

# POST request — send JSON data
curl -s -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"title": "New task", "status": "todo"}'

# Test your local API
curl -s http://localhost:5000/api/tasks | python3 -m json.tool

# POST to your local API
curl -s -X POST http://localhost:5000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Test task", "status": "todo"}'

# Check response headers
curl -I http://localhost:5000/api/tasks

import requests

response = requests.get(
    "https://api.github.com/repos/owner/repo",
    headers={"Accept": "application/vnd.github.v3+json"}
)
if response.status_code == 200:
    data = response.json()
    print(data["description"])
else:
    print(f"Error: {response.status_code}")

from flask import Flask, jsonify, request

app = Flask(__name__)

tasks = []

@app.route("/api/tasks", methods=["GET"])
def get_tasks():
    """Return all tasks, optionally filtered by status."""
    status = request.args.get("status")
    if status:
        filtered = [t for t in tasks if t["status"] == status]
        return jsonify(filtered)
    return jsonify(tasks)

@app.route("/api/tasks", methods=["POST"])
def create_task():
    """Create a new task from JSON body."""
    data = request.get_json()
    if not data or "title" not in data:
        return jsonify({"error": "title is required"}), 400
    task = {
        "id": len(tasks) + 1,
        "title": data["title"],
        "status": data.get("status", "todo"),
    }
    tasks.append(task)
    return jsonify(task), 201

if __name__ == "__main__":
    app.run(debug=True)

# Dockerfile
FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 5000

CMD ["python3", "-m", "flask", "run", "--host=0.0.0.0"]

# docker-compose.yml
services:
  web:
    build: .
    ports:
      - "5000:5000"
    volumes:
      - ./data:/app/data
    environment:
      - FLASK_ENV=development

# Build and run
docker build -t taskforge .
docker run -p 5000:5000 taskforge

# Or use docker-compose
docker compose up --build

**What:** [Feature name and one-sentence description]
**Inputs:** [Parameters with types]
**Outputs:** [Return value and format]
**Constraints:** [Limits, validation rules, security requirements]
**Edge cases:** [Empty input, invalid data, boundary conditions]
**Acceptance criteria:** [Specific, testable conditions]

# Navigate to your project
cd ~/projects/taskforge

# Start Claude Code
claude

# Try Plan Mode first
> Add a delete_task(task_id) function that removes a task by ID.
> Plan first, then implement after I approve.

# ProjectName
One-line description.

## Commands
- `python3 -m pytest` — run tests
- `python3 -m flask run` — start server

## Architecture
- src/ — core logic
- tests/ — test files
- data/ — persistent storage (gitignored)

## Code Style
- Type hints on all function signatures
- Docstrings on all public functions
- No bare try/except

## Gotchas
- [Specific thing Claude gets wrong]
- [Another specific gotcha]

# .claude/skills/[name]/SKILL.md
---
name: skill-name
description: One-line description of what this skill does.
tools: Read, Glob, Grep, Bash
model: opus
---
You are a [role]. Your job is to [task].

## Steps
1. [First step]
2. [Second step]

## Output Format
[What the output should look like]

# .claude/agents/[name].md
---
name: agent-name
description: One-line description.
tools: Read, Glob, Write
model: sonnet
---
[Instructions for the subagent]

Add [feature] to [project].

Requirements:
- [Constraint 1]
- [Constraint 2]

Acceptance criteria:
- All existing tests pass
- New tests cover: [cases]

Run: Work until `python3 -m pytest` passes cleanly.
Fix failures yourself. Don't ask me unless genuinely stuck.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.0
    hooks:
      - id: ruff
      - id: ruff-format
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: python3 -m pytest
        language: system
        pass_filenames: false
        always_run: true

/dispatch [description]:
1) [task 1] — use [model], worktree
2) [task 2] — use [model]
3) [task 3] — use [model]

# Agent Decision Tree

## Simple, one-file task
- **Pattern:** Single session
- **Prerequisites:** None
- **When:** Bug fix, small feature, config change

## Needs exploration
- **Pattern:** Subagents
- **Prerequisites:** Level 3+ (context management)
- **When:** Understanding unfamiliar code, research tasks

## Multiple independent features
- **Pattern:** Dispatch (Level 7)
- **Prerequisites:** Level 6 (harness for backpressure)
- **When:** Sprint of independent work items

## Implementation + QA
- **Pattern:** Builder-Validator (different models)
- **Prerequisites:** Level 5+ (subagent configuration)
- **When:** Any feature that needs quality assurance

## Very large project
- **Pattern:** Agent Teams (Level 8, experimental)
- **Prerequisites:** Level 7, strong CI, clear architecture
- **When:** Multi-system changes requiring coordination