Claude Code

setup-module.md

Setup Module Environment

Set up the development environment for a Python module in this monorepo. Each module uses uv for dependency management.

Setup Process

Step 1: Verify uv is installed

uv --version

If not installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 2: Identify Target Module

Check if current directory has a pyproject.toml or needs one created.

Step 3: Create pyproject.toml if missing

Per CLAUDE.md standards:

• Python >=3.13
• No [build-system] section
• Always include python-dotenv and typer
• Look up latest versions on PyPI

Use the template at .claude/skills/setup-module/templates/pyproject.toml as a starting point.

Step 4: Set up environment

uv sync

Step 5: Create .env if needed

Only create if the module needs environment variables. Keep it minimal.

Step 6: Verify

uv run python -c "import sys; print(f'Python {sys.version}')"

Module Structure

Standard structure per CLAUDE.md:

module_name/
├── pyproject.toml         # Module dependencies
├── .env                   # Environment variables (not in git)
├── README.md              # Module overview and setup
├── src/
│   └── main.py            # Module entry point
└── tests/
    └── samples/           # Test sample files

Adding Cross-Module Dependencies

If your module needs to import from another module in the monorepo:

uv add --editable ../other-module

This updates pyproject.toml with a path dependency in editable mode, so changes to the other module are reflected immediately.

Example: If ct-applications needs to import from windows-control:

cd ct-applications
uv add --editable ../windows-control

Then in your Python code:

from smb import SMBClient  # Just works!

Important: Never use sys.path.insert() or sys.path.append() for cross-module imports.

Notes

• Use uv run to execute scripts
• Use uv add package to add dependencies
• Never commit .env files
• Keep pyproject.toml simple - only add dependencies you actually need

summarize.md

Summarize this conversation in a structured format:

Topics Discussed

List the main topics as bullet points (3-7 items)

Decisions Made

List any decisions or conclusions reached

Actions Taken

List files created, modified, or commands run

Open Items

List anything unfinished or pending follow-up

Keep each section concise (1-2 sentences per item max).

wrap-up.md

description
Wrap up session with git commit and temp file cleanup

Wrap Up Session

Help the user cleanly wrap up their current work session.

Steps

1. Update working document log

If the session involved an ost-*.md file or similar planning document with a Log section:

• Add a dated entry summarizing what was accomplished
• Include key decisions, discoveries, or blockers encountered
• Reference any new runbooks or scripts created
• Note pending work that follows from this session

This ensures institutional memory beyond just git commits.

2. Check for uncommitted changes

Run git status and git diff --stat to see what's been modified.

3. Draft commit message (if changes exist)

If there are changes to commit:

• Summarize WHAT changed
• Explain WHY it was done (the motivation, context, trade-offs)
• Mention if anything was tried and reverted
• Treat the commit message as a journal entry for future developers

Ask the user if they want to commit with the drafted message.

4. Clean up temp files

Look for test artifacts that may have been created:

• /tmp/ files related to this session
• tmp/ directories within modules
• pdf_previews/, test_output/, or similar generated folders
• Any files mentioned during the conversation that were for testing

List what you find and ask the user which to clean up.

5. Runbook Opportunity

Runbooks are the default output of any non-trivial session. Ask:

• Did we figure out a procedure that's worth documenting?
• Were there gotchas or troubleshooting steps we discovered?
• Even if one-off, might we need to undo this or do something similar later?

If yes, suggest creating a runbook in the relevant module's runbooks/ directory. A runbook captures:

• What we did and why
• Step-by-step procedure
• Gotchas and troubleshooting
• Lessons learned

Example: "We set up Scanner user on PCs - this should be a runbook at windows-control/runbooks/scanner-user-setup.md"

6. Session Pattern Analysis

Review this conversation for automation opportunities. Look for:

1. Repetitive tool sequences: Did we call the same tools in sequence multiple times? (e.g., Grep → Read → Edit pattern)
2. Context we had to provide repeatedly: Information the user explained that could be in CLAUDE.md or a skill
3. Manual lookups: Web searches, file reads, or questions that could be pre-answered by a command
4. Multi-step workflows: Tasks that required orchestration and could be a single command
5. Domain knowledge gaps: Things we had to learn mid-session that future sessions shouldn't need to re-learn

For each pattern found, suggest:

• Command: A .claude/commands/name.md file for user-invokable shortcuts
• Skill: A .claude/skills/name/SKILL.md for AI-matchable capabilities
• CLAUDE.md addition: Context that should be permanent

Example output:

Session patterns detected:

1. COMMAND OPPORTUNITY: /ethanol-model
   - Pattern: Web search for Panama data → update HTML model → recalculate
   - Would save: ~10 tool calls per iteration

2. SKILL OPPORTUNITY: panama-data-lookup
   - Pattern: Searched for Panama vehicle fleet, fuel prices, ethanol laws
   - Could pre-load common Panama statistics

3. CLAUDE.MD ADDITION:
   - Panama's ethanol mandate timeline (E5 2026 → E7 2027 → E10 2028)
   - Saves explaining this context in future sessions

7. Further Automation

If a runbook already exists or was just created, check if parts can progress further:

1. Runbook → Skill: Can AI do this more autonomously? Create a skill in .claude/skills/skill-name/SKILL.md (case-sensitive). See skill format below.
2. Runbook → Script: Are parts deterministic enough to automate? Extract to scripts/.
3. Script → Cron/Systemd: Is a script stable enough to run unattended?

8. Summary

Provide a brief summary of what was accomplished in the session.

---

Skill Format Reference

When creating a skill, use this structure:

.claude/skills/skill-name/
└── SKILL.md        # Case-sensitive filename required

SKILL.md must have YAML frontmatter:

---
name: skill-name
description: When to use this skill (Claude uses this for auto-matching)
---

# Skill Title

## Instructions
[What Claude should do when this skill is invoked]

For skills that live in module directories, use symlinks:

mkdir -p .claude/skills/skill-name
ln -s ../../../module/SKILL.md .claude/skills/skill-name/SKILL.md