claude-gen/.claude/plans/update-fission-skill.md

# Plan: Update FissionPython Skill

## Context

The `fission-python-skill` plugin needs to be updated to meet new requirements for Fission Python projects:

1. **Build script**: `src/build.sh` must exist and be referenced correctly in `.fission/deployment.json`
2. **Dependencies**: `src/requirements.txt` must exist and contain necessary packages (pydantic, etc.)
3. **CI/CD**: All projects must include `.gitea/workflows/` directory with deployment workflows
4. **API Design**: HTTP trigger functions must use Pydantic models for request/response validation
5. **Documentation**: All functions must have proper docstrings and code comments
6. **Portability**: Remove hardcoded absolute paths - the plugin should work from any location

Current issues:
- `create-project.sh` uses hardcoded path `/workspaces/claude-marketplace/data/py-eom-quota`
- Template resides in `data/examples/` which is outside the plugin
- No validation of generated projects
- Documentation references incorrect paths

## Approach

**Step 1: Make Plugin Portable**
- Copy the `py-eom-quota` template into `fission-python-skill/template/`
- Update `create-project.sh` to find template relative to script location using `dirname "$0"`
- Remove all absolute path references

**Step 2: Add Project Validation**
Enhance `create-project.sh` with post-creation validation:
- Check `src/build.sh` exists and is executable
- Verify `.fission/deployment.json` references the correct build command (`./build.sh`)
- Check `src/requirements.txt` exists and contains required dependencies:
  - `pydantic==2.x`
  - `flask` (for HTTP handlers)
  - `psycopg2-binary` or `psycopg2` (if database usage)
- Verify `.gitea/workflows/` directory exists with the 4 standard workflow files
- Validate that function files contain pydantic models (basic grep check)
- Warn if docstrings appear minimal or missing

**Step 3: Update Documentation**
- Fix `SKILL.md` and `reference.md` to reference the correct template path
- Document the new validation checks
- Update examples to show portable usage

**Step 4: Potentially Add New Tool**
Consider adding a separate validation tool (`validate-project.sh`) that can be run on existing projects to check compliance with standards.

## Critical Files to Modify

1. **`fission-python-skill/create-project.sh`**
   - Change `TEMPLATE_DIR` to use relative path: `$(dirname "$0")/template`
   - Add validation functions after project creation
   - Improve error messages
   - Add warnings for missing documentation

2. **`fission-python-skill/template/`** (new directory)
   - Copy entire structure from `data/examples/py-eom-quota/`
   - Ensure `build.sh` has correct permissions (755)
   - Verify all configuration files

3. **`fission-python-skill/SKILL.md`** and **`reference.md`**
   - Update template path references
   - Document validation behavior
   - Update examples

4. **`.claude-plugin/marketplace.json`**
   - No changes needed (plugin registration OK)

## Implementation Details

### Template Structure
```
fission-python-skill/
└── template/
    ├── .fission/
    │   ├── deployment.json
    │   ├── dev-deployment.json
    │   └── local-deployment.json
    ├── .gitea/
    │   └── workflows/
    │       ├── dev-deployment.yaml
    │       ├── install-dispatch.yaml
    │       ├── uninstall-dispatch.yaml
    │       └── analystic-dispatch.yaml
    ├── src/
    │   ├── build.sh (executable)
    │   ├── requirements.txt (with pydantic, flask, etc.)
    │   ├── models.py (with pydantic models)
    │   ├── exceptions.py
    │   ├── helpers.py
    │   ├── vault.py
    │   └── <example functions>.py (with docstrings and pydantic usage)
    ├── test/
    ├── manifests/
    ├── migrates/
    ├── specs/
    ├── dev-requirements.txt
    ├── README.md
    ├── .gitignore
    └── .devcontainer/
```

### Validation Checklist in create-project.sh
After copying template and doing substitutions:
1. `[ -f "$PROJECT_PATH/src/build.sh" ]` || warning
2. `[ -x "$PROJECT_PATH/src/build.sh" ]` || chmod +x
3. Check `deployment.json` contains `"./build.sh"` in packages.buildcmd
4. `[ -f "$PROJECT_PATH/src/requirements.txt" ]` || error
5. Check requirements.txt contains `pydantic` (grep -q "pydantic")
6. Check requirements.txt contains `flask` (grep -q "flask")
7. `[ -d "$PROJECT_PATH/.gitea/workflows" ]` || warning/copy from template
8. Count workflow files: should have at least 4 .yaml files
9. Optional: Check that Python files have docstrings (grep for triple quotes)
10. Optional: Check for pydantic BaseModel usage in models.py

### Portable Path Resolution
```bash
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
TEMPLATE_DIR="$SCRIPT_DIR/template"
```

This ensures the plugin works regardless of where it's invoked from.

## Verification Steps

1. **Test create-project**:
   - Run `./fission-python-skill/create-project.sh test-project ./tmp/`
   - Verify all expected directories/files exist
   - Check that validation warnings/errors appear appropriately

2. **Test portability**:
   - Move plugin to a different directory
   - Run create-project from there
   - Should still work without path adjustments

3. **Test validation**:
   - Manually delete `src/requirements.txt` from template and create project → should error
   - Remove pydantic from requirements.txt → should warn
   - Remove .gitea/workflows → should warn
   - Change build.sh buildcmd to something else → should warn

4. **Test generated project**:
   - Verify functions have docstrings with fission config blocks
   - Verify models.py uses pydantic BaseModel
   - Verify HTTP triggers properly defined in deployment.json

## Risks and Considerations

- **Template duplication**: Moving template into plugin duplicates existing examples. That's acceptable - the examples in `data/examples/` are finished projects, while the template is a starter. Keep both.
- **Validation strictness**: Start with warnings for most checks, errors only for critical missing files (requirements.txt build.sh). Can tighten later.
- **Template maintenance**: When updating the template, only modify `fission-python-skill/template/`. The examples in `data/examples/` are independent and can diverge if needed.

## Post-Implementation

- Update any scripts or docs that reference the old template path
- Test the skill end-to-end through Claude Code
- Consider adding a `validate-project.sh` tool for existing projects