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

```bash
# 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:

```python
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