claude-gen/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is a Claude Marketplace repository — a plugin ecosystem for Claude Code. It contains:

• Plugin Registry (.claude-plugin/marketplace.json): Defines available plugins/skills
• Fission Python Skill (fission-python/): Plugin providing tools for Fission serverless Python projects
• Example Projects (data/examples/): Example Fission Python projects (py-eom-quota, py-eom-storage, py-ailbl-scheduler)
• Fission Python Template (fission-python/template/): Default template used when creating new Fission Python projects

Note: .sdlc-agents/ is not part of this repo. It is bind-mounted into the devcontainer from ~/Workspaces/self/sdlc-agents/agents on the host.

Plugin System Architecture

Claude Code discovers plugins via .claude-plugin/marketplace.json at the repository root. Each plugin entry:

• Has an id, name, description, type (skill), path, and tools array
• Points to a directory containing the tool implementations (executable .sh scripts)

The fission-python plugin (fission-python/.claude-plugin/plugin.json) exposes three tools:

• create-project — create-project.sh
• analyze-config — analyze-config.sh
• update-docstring — update-docstring.sh

Both marketplace.json (registry) and plugin.json (plugin definition) must be present for discovery to work.

Working with the Fission Python Skill

# Make scripts executable (required after fresh clone)
chmod +x fission-python/*.sh

# Create a new Fission Python project
./fission-python/create-project.sh <project-name> [destination]

# Analyze .fission configuration in an existing project
./fission-python/analyze-config.sh <project-path>    # requires jq

# View or update Fission config embedded in a function docstring
./fission-python/update-docstring.sh <file.py> <function-name> --get
./fission-python/update-docstring.sh <file.py> <function-name> --set '<json>'

Fission Configuration in Docstrings

Fission config is embedded between ```fission and ``` markers in Python function docstrings:

def main():
    """
    ```fission
    {
        "name": "function-name",
        "http_triggers": {
            "trigger-name": {"url": "/endpoint", "methods": ["GET"]}
        }
    }
    ```
    """

The update-docstring.sh tool parses and updates these blocks.

Updating the Project Template

The template lives in fission-python/template/. When create-project.sh runs, it copies this directory and performs string substitutions (e.g., replacing project name). The plugin locates the template relative to its own position, making it portable.

Key template areas to modify:

• src/ — default function structure and helpers
• .fission/deployment.json — default environment/package/function config
• .gitea/workflows/ — CI/CD pipeline workflows
• requirements.txt / dev-requirements.txt — dependencies

Testing

No centralized test runner. Test skill scripts by running them directly with various arguments, verifying argument parsing, file operations, and JSON output. Example projects in data/examples/ use pytest.

Configuration

• .claude/settings.json — Claude Code settings (plans directory)
• .claude-plugin/marketplace.json — Plugin registry
• fission-python/.claude-plugin/plugin.json — Plugin definition

Development Environment (Devcontainer)

The .devcontainer/devcontainer.json configures a VS Code dev container with:

• postStartCommand: .devcontainer/setup.sh
• Bind mount: ~/Workspaces/self/sdlc-agents/agents → .sdlc-agents/ (external SDLC system)

Environment variables set in devcontainer:

Variable	Default	Purpose
ANTHROPIC_API_KEY	(empty)	API key
ANTHROPIC_BASE_URL	https://openrouter.ai/api	API endpoint
ANTHROPIC_MODEL	stepfun/step-3.5-flash:free	Default model
ANTHROPIC_SMALL_FAST_MODEL	nvidia/nemotron-3-super-120b-a12b:free	Alternate model

Common Pitfalls

• Plugin tools must be executable: Run chmod +x fission-python/*.sh
• jq dependency: analyze-config.sh requires jq for JSON parsing
• sed portability: Scripts use GNU sed — on macOS use sed -i '' instead of sed -i
• Template exclusions: create-project.sh excludes .git, __pycache__, *.pyc, .env on copy
• SDLC agents: Only available inside devcontainer (bind-mounted, not in this repo)

AI Guidelines

Planning Rule

Before making code changes for non-trivial tasks:

1. Use EnterPlanMode to create a detailed implementation plan
2. Explore the codebase to understand existing patterns
3. Present the plan for approval before implementing
4. Use TaskList to track progress on multi-step tasks

Agent Usage Rule

Use agents for complex, multi-step, or parallelizable tasks:

• Research/exploration → Explore agent
• Implementation planning → Plan agent