ref: up
This commit is contained in:
Duc Nguyen
509
README.md
Normal file
509
README.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# Claude Marketplace
|
||||
|
||||
[](https://fission.io/)
|
||||
[](https://python.org)
|
||||
[](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.
|
||||
Reference in New Issue
Block a user