Files
claude-gen/README.md

510 lines
18 KiB
Markdown
Raw Normal View History

2026-03-18 20:21:56 +07:00
# Claude Marketplace
[![Fission](https://img.shields.io/badge/Fission-Serverless%20Kubernetes-blue)](https://fission.io/)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://python.org)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-AI%20Assistant-orange)](https://claude.ai/code)
A plugin ecosystem for Claude Code featuring the **Fission Python Skill** for serverless Python projects and a complete **SDLC Agent System** for automated software development workflows.
## Table of Contents
- [Overview](#overview)
- [Fission Python Skill](#fission-python-skill)
- [SDLC Agent System](#sdlc-agent-system)
- [Project Structure](#project-structure)
- [Quick Start](#quick-start)
- [Development](#development)
- [Configuration](#configuration)
- [Related Documentation](#related-documentation)
- [Key Technologies](#key-technologies)
## Overview
Claude Marketplace is a repository that provides extensible plugins and tools for Claude Code, Anthropic's AI-powered development environment. It contains two major components:
1. **Fission Python Skill** - A plugin for creating, analyzing, and managing Fission serverless Python projects on Kubernetes
2. **SDLC Agent System** - A complete multi-agent Software Development Life Cycle system for automated planning, architecture validation, coding, and code review
These components work independently but can be used together to create and maintain production-ready software with AI assistance.
## Fission Python Skill
The Fission Python Skill provides three essential tools for working with [Fission](https://fission.io/) serverless functions written in Python.
### When to Use
- Creating new Fission Python projects from a standardized template
- Analyzing existing Fission configuration files
- Parsing and updating Fission configuration embedded in Python function docstrings
### Available Tools
| Tool | Purpose |
|------|---------|
| `create-project.sh` | Create new Fission Python project from template |
| `analyze-config.sh` | Analyze `.fission` configuration in a project |
| `update-docstring.sh` | Parse and update Fission config in function docstrings |
### Installation
The skill scripts are ready to use. Make them executable:
```bash
chmod +x fission-python-skill/*.sh
```
### Usage Examples
**Create a new Fission project:**
```bash
./fission-python-skill/create-project.sh my-function ./projects/
```
**Analyze project configuration:**
```bash
./fission-python-skill/analyze-config.sh ./my-fission-project
```
**View function configuration:**
```bash
./fission-python-skill/update-docstring.sh ./src/func.py main --get
```
**Update function configuration:**
```bash
./fission-python-skill/update-docstring.sh ./src/func.py main --set '{"http_triggers": {"api": {"url": "/v1/data", "methods": ["GET"]}}}'
```
### Project Structure
Projects created with `create-project.sh` follow the standard Fission Python layout:
```
project/
├── .fission/
│ ├── deployment.json # Main configuration
│ ├── dev-deployment.json # Development overrides
│ └── local-deployment.json # Local overrides
├── src/ # Python function source files
│ └── function.py # Functions with fission config in docstrings
├── specs/ # Generated Fission specs
├── test/ # Unit tests
├── manifests/ # Kubernetes manifests
├── migrates/ # Database migrations
├── requirements.txt # Runtime dependencies
└── dev-requirements.txt # Development dependencies
```
### Fission Configuration in Docstrings
Fission configuration is embedded in Python function docstrings between ````fission` and ```` markers:
```python
def main():
"""
```fission
{
"name": "function-name",
"http_triggers": {
"trigger-name": {
"url": "/endpoint",
"methods": ["GET", "POST"]
}
}
}
```
"""
# implementation
```
The `update-docstring.sh` tool parses and updates these configurations.
## SDLC Agent System
The SDLC (Software Development Life Cycle) Agent System is a complete multi-agent framework for automated software development. It orchestrates seven specialized agents to take a feature request from planning through implementation and review.
### The Seven Agents
| Agent | Role | Key Responsibilities |
|-------|------|---------------------|
| **Initializer** | Setup | Initialize `agent-context/`, detect stack, generate harness scripts, populate domain skills |
| **Planning** | Planning | Transform requests into structured, architecture-aware plans with isolated tasks |
| **Architect** | Review | Evaluate architecture, enforce architectural rules, validate design decisions |
| **Coding** | Implementation | Implement one task at a time from self-contained task files |
| **Code Review** | Quality | Review code for correctness, architecture adherence, and debt awareness |
| **Curator** | Orchestration | Manage task progression, feature completion, and handoffs |
| **Retro** | Improvement | Conduct retrospectives and process improvement |
### Agent Workflow
```
User Request
Initializer (one-time setup)
Planning Agent (creates feature + tasks)
Architect Agent (reviews plan)
Coding Agent (implements task 1)
Coding Agent (implements task 2)
...
Code Review Agent (reviews implementation)
Curator (approves/requests changes)
Feature Complete
```
### Setup
To use the SDLC Agent System in a project:
```bash
# Copy agent templates to project root
./.sdlc-agents/setup.sh /path/to/target-project
# This creates: /path/to/target-project/agent-context/
# with harness/, memory/, features/, and extensions/ directories
```
The setup is **idempotent** - safe to run multiple times. Use `-f` to force overwrite existing files.
### Agent Context Structure
After setup, the project will have:
```
agent-context/
├── harness/ # Task execution scripts and tracking
│ ├── init-project.sh
│ ├── run-quality-gates.sh
│ ├── run-arch-tests.sh
│ ├── run-feature.sh
│ ├── start-task.sh
│ └── ...
├── memory/ # Learning playbook and retrieval
│ └── learning-playbook.md
├── features/ # Feature specs and task definitions
│ ├── FEAT-001/
│ │ ├── feature.md # Feature context
│ │ ├── progress-log.md # Progress tracking
│ │ └── tasks/
│ │ ├── T01-setup.md
│ │ └── T02-implement.md
└── extensions/ # Custom rules and skills
├── _all-agents/ # Global constraints
├── planning-agent/
├── architect-agent/
├── coding-agent/
├── codereview-agent/
└── skills/ # Project-specific skills
├── domain/
└── ...
```
### Skill System
Agents can load domain-specific skills that provide patterns, constraints, and guidance:
**Stack Skills** (auto-detected):
- Java/Kotlin, TypeScript/JavaScript, Python, Go, Rust, .NET/C#, Ruby, PHP
**Pattern Skills** (on-demand):
- Hexagonal, Layered, Modular Monolith, Microservices, Spec-Driven
**Framework Skills**:
- Embabel
Skills are discovered using `stack-detection.md` and can be explicitly requested via skill directives:
- `#TDD` - Force-load TDD skill
- `#Hexagonal,Clean` - Load multiple skills
- `#only:Python,Security` - Use only these skills
- `!Kafka` - Exclude a skill
### Harness and Quality Gates
The generated harness scripts provide:
- **`init-project.sh`** - Install dependencies, compile, verify environment
- **`run-quality-gates.sh`** - Run all quality checks (tests, lint, arch, coverage, security)
- **`run-arch-tests.sh`** - Run architecture validation tests
- **`run-feature.sh`** - Run tests for a specific feature
- **`start-task.sh`** - Mark task as in_progress
- **`collect-metrics.sh`**, **`compare-metrics.sh`**, **`archive-metrics.sh`** - Metrics management
These scripts are **stack-specific** - generated based on the detected technology stack and configured tools.
## Project Structure
```
claude-marketplace/
├── .claude-plugin/
│ └── marketplace.json # Plugin registry for Claude Code
├── .sdlc-agents/ # Complete SDLC agent system
│ ├── agents/ # Agent configurations (7 agents)
│ │ ├── initializer-agent.md
│ │ ├── planning-agent.md
│ │ ├── architect-agent.md
│ │ ├── coding-agent.md
│ │ ├── codereview-agent.md
│ │ ├── curator-agent.md
│ │ └── retro-agent.md
│ ├── guardrails/ # Quality guidelines
│ ├── skills/ # Stack, pattern, and framework skills
│ │ ├── stacks/ # Language-specific (Python, Java, TS, Go, etc.)
│ │ ├── patterns/ # Architecture patterns
│ │ └── frameworks/ # Framework-specific guidance
│ ├── templates/ # Templates for agent-context structure
│ ├── tools/ # Utility scripts (discovery, validation, skills)
│ └── setup.sh # Initialize agent-context in a project
├── fission-python-skill/ # Fission Python plugin
│ ├── .claude-plugin/
│ │ └── plugin.json # Plugin definition
│ ├── template/ # Project template (copied when creating new projects)
│ │ ├── .fission/
│ │ ├── src/
│ │ ├── test/
│ │ ├── manifests/
│ │ ├── migrates/
│ │ ├── specs/
│ │ ├── requirements.txt
│ │ └── dev-requirements.txt
│ ├── create-project.sh # Create new Fission project
│ ├── analyze-config.sh # Analyze .fission configuration
│ ├── update-docstring.sh # Parse/update function docstrings
│ ├── SKILL.md # Quick reference
│ └── reference.md # Detailed tool documentation
├── data/
│ └── examples/ # Example Fission Python projects
│ ├── py-eom-quota/
│ ├── py-eom-storage/
│ └── py-ailbl-scheduler/
└── .devcontainer/ # VS Code dev container configuration
└── devcontainer.json
```
## Quick Start
### Setting Up Development Environment
**Recommended:** Open the repository in a devcontainer (VS Code with Dev Containers extension):
```bash
# Open in container from VS Code
# The devcontainer will set up dependencies and environment
```
**Manual setup:**
```bash
# Make scripts executable
chmod +x fission-python-skill/*.sh
chmod +x .sdlc-agents/setup.sh
```
### Using the Fission Python Skill
1. **Create a new Fission project:**
```bash
./fission-python-skill/create-project.sh my-api ./projects/
```
2. **Analyze the configuration:**
```bash
./fission-python-skill/analyze-config.sh ./projects/my-api
```
3. **Develop your function** in `src/`, update docstrings as needed with `update-docstring.sh`
4. **Deploy to Fission** following Fission documentation
### Using the SDLC Agent System
1. **Initialize an existing project** (new or legacy):
```bash
./.sdlc-agents/setup.sh /path/to/your/project
```
2. The Initializer Agent will:
- Detect the technology stack
- Generate stack-specific harness scripts
- Create initial feature structure
- Populate domain skills based on project analysis
- For legacy projects: discover and document architecture
3. **Start a new feature:**
- Create a feature request in `agent-context/features/`
- The Planning Agent will create detailed task files
- The Architect Agent will review and approve the plan
- Coding Agents implement each task
- Code Review Agents validate each implementation
- Curator manages handoffs and completion
4. **Run quality gates:**
```bash
cd /path/to/your/project
./agent-context/harness/run-quality-gates.sh
```
### Testing Changes
- **Fission skill scripts:** Run directly with various arguments
- **Template projects:** Use pytest in generated projects
- **SDLC agents:** Run `setup.sh` and verify `agent-context/` creation
## Development
### Modifying Fission Python Skill
1. Edit scripts in `fission-python-skill/`
2. Update `plugin.json` to modify tools or metadata
3. Update `marketplace.json` to change plugin registry
4. Test by running scripts directly
### Updating the Project Template
The template at `fission-python-skill/template/` is used by `create-project.sh`:
- Modify `src/` to change default function structure
- Update `.fission/deployment.json` for environment configuration
- Adjust `requirements.txt` for different dependencies
- The template `build.sh` is used when building packages
- Ensure `.gitea/workflows/` includes CI/CD workflows
The plugin locates the template relative to its own location, making it portable.
### Plugin Registration
Both files must be present:
- `.claude-plugin/marketplace.json` (registry - lists all plugins)
- `fission-python-skill/.claude-plugin/plugin.json` (plugin definition)
### Invoking Skills in Claude Code
Once registered, skills can be invoked through Claude Code's tool system. The tool names correspond to the script basenames:
- `create-project`
- `analyze-config`
- `update-docstring`
## Configuration
### Environment Variables (Dev Container)
Set in `.devcontainer/devcontainer.json`:
| Variable | Default | Purpose |
|----------|---------|---------|
| `ANTHROPIC_API_KEY` | (empty) | API key (mounted from local) |
| `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 |
### Claude Code Settings
- `.claude/settings.json` - Main settings (plans directory, hooks)
- `.claude/settings.local.json` - Local overrides (not committed)
### Dependencies
The `analyze-config.sh` tool requires `jq` for JSON parsing:
```bash
# Debian/Ubuntu
sudo apt-get install jq
# macOS
brew install jq
```
## Related Documentation
### Comprehensive Guides
- **[CLAUDE.md](CLAUDE.md)** - Complete project guide with detailed architecture and workflows
### Fission Python Skill
- **[fission-python-skill/SKILL.md](fission-python-skill/SKILL.md)** - Quick reference and usage patterns
- **[fission-python-skill/reference.md](fission-python-skill/reference.md)** - Detailed tool documentation
### SDLC Agents
- **[.sdlc-agents/skills/README.md](.sdlc-agents/skills/README.md)** - Skill system usage and discovery
- **[.sdlc-agents/initializer-agent.md](.sdlc-agents/initializer-agent.md)** - Setup agent documentation
- **[.sdlc-agents/planning-agent.md](.sdlc-agents/planning-agent.md)** - Planning agent documentation
- **[.sdlc-agents/architect-agent.md](.sdlc-agents/architect-agent.md)** - Architecture review agent
- **[.sdlc-agents/coding-agent.md](.sdlc-agents/coding-agent.md)** - Implementation agent
- **[.sdlc-agents/codereview-agent.md](.sdlc-agents/codereview-agent.md)** - Code review agent
- **[.sdlc-agents/curator-agent.md](.sdlc-agents/curator-agent.md)** - Orchestration agent
- **[.sdlc-agents/retro-agent.md](.sdlc-agents/retro-agent.md)** - Retrospective agent
- **[.sdlc-agents/skills/harness-spec.md](.sdlc-agents/skills/harness-spec.md)** - Harness specification
## Key Technologies
- **Fission** - Serverless framework for Kubernetes
- **Python** - Primary language for the Fission skill plugin
- **Claude Code** - AI-powered development environment by Anthropic
- **Kubernetes** - Container orchestration platform for Fission
- **SDLC Agents** - Multi-agent system for automated software development
- **Shell scripting** - Tool implementations (Bash with `jq` for JSON)
## Common Pitfalls
- **Plugin tools must be executable**: Always run `chmod +x` on `.sh` files
- **Do not commit secrets**: `.env` files are gitignored; template creates placeholder only
- **Plugin registration**: Both `marketplace.json` AND plugin's `plugin.json` must exist
- **Template path**: `create-project.sh` uses relative path to `fission-python-skill/template/` (portable)
- **jq dependency**: `analyze-config.sh` requires `jq` installed
- **sed portability**: Scripts use GNU sed; may need adjustment for macOS (`sed -i ''`)
## Quick Reference
### Fission Python Skill
```bash
# Create new project
fission-python-skill/create-project.sh my-project ./output/
# Analyze configuration
fission-python-skill/analyze-config.sh ./existing-project
# View docstring config
fission-python-skill/update-docstring.sh ./src/func.py main --get
# Update docstring config
fission-python-skill/update-docstring.sh ./src/func.py main --set '{"http_triggers": {"api": {"url": "/v1", "methods": ["GET"]}}}'
```
### SDLC Agent System
```bash
# Setup agents in a project
.sdlc-agents/setup.sh /path/to/project
# Resolve skill paths for planning agent
.sdlc-agents/tools/skills/resolve-skills.sh --agent planning python tdd
# Parse skill directives from user prompt
.sdlc-agents/tools/skills/parse-skill-directives.sh "Use #Hexagonal but !Kafka"
```
### Harness Scripts (after setup)
```bash
# Initialize project (install deps, compile)
./agent-context/harness/init-project.sh
# Run all quality checks
./agent-context/harness/run-quality-gates.sh
# Run architecture tests only
./agent-context/harness/run-arch-tests.sh
# Run feature-specific tests
./agent-context/harness/run-feature.sh FEAT-001
```
---
Built for the Claude Code ecosystem. See [CLAUDE.md](CLAUDE.md) for comprehensive documentation.