183 lines
6.2 KiB
Markdown
183 lines
6.2 KiB
Markdown
|
# README.md Generation Plan
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
The user requested to "review project and generate README.md file" for the Claude Marketplace repository. This repository contains a plugin ecosystem for Claude Code with two major components:
|
||
|
|
|
||
|
|
1. **Fission Python Skill** - A plugin for creating, analyzing, and managing Fission serverless Python projects
|
||
|
|
2. **SDLC Agent System** - A complete multi-agent Software Development Life Cycle system for automated planning, architecture, coding, and code review
|
||
|
|
|
||
|
|
The repository is missing a root-level README.md file that documents these components, their usage, and how they work together.
|
||
|
|
|
||
|
|
## Problem Statement
|
||
|
|
|
||
|
|
The repository needs a comprehensive README.md at the root level that:
|
||
|
|
|
||
|
|
1. Introduces the Claude Marketplace project and its purpose
|
||
|
|
2. Documents the Fission Python Skill plugin (tools, installation, usage)
|
||
|
|
3. Documents the SDLC Agent System (agents, setup, workflow)
|
||
|
|
4. Explains the project structure and key directories
|
||
|
|
5. Provides quick start guides for both components
|
||
|
|
6. Includes reference information (technologies, environment variables, common tasks)
|
||
|
|
7. Links to existing detailed documentation (CLAUDE.md, agent docs, skill docs)
|
||
|
|
|
||
|
|
## Solution Approach
|
||
|
|
|
||
|
|
### What to Include
|
||
|
|
|
||
|
|
Based on repository analysis, the README should cover:
|
||
|
|
|
||
|
|
1. **Project Overview**
|
||
|
|
- What is Claude Marketplace?
|
||
|
|
- Key components (Fission Python Skill, SDLC Agents)
|
||
|
|
- Relationship between components
|
||
|
|
|
||
|
|
2. **Fission Python Skill**
|
||
|
|
- Purpose and use cases
|
||
|
|
- Available tools (create-project, analyze-config, update-docstring)
|
||
|
|
- Installation/setup (chmod +x on scripts)
|
||
|
|
- Usage examples for each tool
|
||
|
|
- Project structure
|
||
|
|
- Links to detailed docs (SKILL.md, reference.md)
|
||
|
|
|
||
|
|
3. **SDLC Agent System**
|
||
|
|
- Overview of the 7 agents (Initializer, Planning, Architect, Coding, Code Review, Curator, Retro)
|
||
|
|
- Agent workflow and handoffs
|
||
|
|
- Setup procedure (setup.sh script)
|
||
|
|
- agent-context directory structure
|
||
|
|
- Skills system (stack detection, patterns, frameworks)
|
||
|
|
- Quality gates and harness scripts
|
||
|
|
- Links to detailed agent docs
|
||
|
|
|
||
|
|
4. **Project Structure**
|
||
|
|
- Directory layout with descriptions
|
||
|
|
- Key configuration files
|
||
|
|
- Template locations
|
||
|
|
|
||
|
|
5. **Quick Start**
|
||
|
|
- Using Fission Python Skill to create a project
|
||
|
|
- Setting up SDLC Agents in an existing project
|
||
|
|
- Development environment (devcontainer)
|
||
|
|
|
||
|
|
6. **Development**
|
||
|
|
- Making changes to skill scripts
|
||
|
|
- Updating plugin metadata
|
||
|
|
- Testing approaches
|
||
|
|
|
||
|
|
7. **Configuration**
|
||
|
|
- Environment variables (for devcontainer)
|
||
|
|
- Claude Code settings
|
||
|
|
|
||
|
|
8. **Related Documentation**
|
||
|
|
- CLAUDE.md (comprehensive project guide)
|
||
|
|
- Agent-specific documentation
|
||
|
|
- Skill documentation
|
||
|
|
|
||
|
|
### Design Decisions
|
||
|
|
|
||
|
|
- **Structure**: Standard GitHub README with clear sections using markdown headings
|
||
|
|
- **Tone**: Professional, concise, informative
|
||
|
|
- **Format**: Single file at repository root
|
||
|
|
- **Links**: Cross-reference existing documentation rather than duplicating content
|
||
|
|
- **Code blocks**: Include practical examples for all commands
|
||
|
|
- **Tables**: Use for quick reference (tools, skills, agents)
|
||
|
|
|
||
|
|
### Reuse Existing Content
|
||
|
|
|
||
|
|
- CLAUDE.md contains excellent detailed information - will summarize and link to it
|
||
|
|
- Individual agent .md files have authoritative content - will link rather than copy
|
||
|
|
- Skill files (SKILL.md) already have user-facing docs - will summarize and link
|
||
|
|
- The template structure is documented in CLADE.md - will extract key info
|
||
|
|
|
||
|
|
## Implementation Steps
|
||
|
|
|
||
|
|
1. Create `/workspaces/claude-marketplace/README.md` with:
|
||
|
|
|
||
|
|
a. **Header section**
|
||
|
|
- Badges (if applicable)
|
||
|
|
- Title and subtitle
|
||
|
|
- One-sentence description
|
||
|
|
|
||
|
|
b. **Table of Contents** (auto-generated with markdown-toc or manual)
|
||
|
|
|
||
|
|
c. **Project Overview**
|
||
|
|
- Purpose of Claude Marketplace
|
||
|
|
- Components summary
|
||
|
|
- Key technologies
|
||
|
|
|
||
|
|
d. **Fission Python Skill section**
|
||
|
|
- Description
|
||
|
|
- Tools table
|
||
|
|
- Installation
|
||
|
|
- Usage examples
|
||
|
|
- Project structure
|
||
|
|
- Links to SKILL.md and reference.md
|
||
|
|
|
||
|
|
e. **SDLC Agent System section**
|
||
|
|
- What are SDLC Agents?
|
||
|
|
- The 7 agents with brief descriptions
|
||
|
|
- Setup instructions
|
||
|
|
- Agent-context structure
|
||
|
|
- Skills system overview
|
||
|
|
- Harness and quality gates
|
||
|
|
- Links to detailed docs
|
||
|
|
|
||
|
|
f. **Project Structure section**
|
||
|
|
- Directory tree visualization
|
||
|
|
- Key files table
|
||
|
|
|
||
|
|
g. **Quick Start section**
|
||
|
|
- Setting up dev environment
|
||
|
|
- Creating Fission project
|
||
|
|
- Initializing SDLC Agents
|
||
|
|
|
||
|
|
h. **Development section**
|
||
|
|
- Modifying skills
|
||
|
|
- Plugin registration
|
||
|
|
- Testing
|
||
|
|
|
||
|
|
i. **Configuration section**
|
||
|
|
- Environment variables table
|
||
|
|
- Settings files
|
||
|
|
|
||
|
|
j. **License** (check if exists)
|
||
|
|
|
||
|
|
2. Ensure the README:
|
||
|
|
- Is comprehensive but concise
|
||
|
|
- Uses consistent formatting (h2 for major sections, h3 for subsections)
|
||
|
|
- Includes practical examples with code blocks
|
||
|
|
- Links to existing detailed documentation
|
||
|
|
- Has a clear call-to-action for both components
|
||
|
|
|
||
|
|
3. Quality checks:
|
||
|
|
- Verify all linked files exist
|
||
|
|
- Ensure markdown renders properly (no broken syntax)
|
||
|
|
- Check for consistency with CLAUDE.md
|
||
|
|
|
||
|
|
## Critical Files
|
||
|
|
|
||
|
|
- `/workspaces/claude-marketplace/README.md` - The file to create
|
||
|
|
- `/workspaces/claude-marketplace/CLAUDE.md` - Source for detailed project information
|
||
|
|
- `/workspaces/claude-marketplace/fission-python-skill/SKILL.md` - Skill documentation source
|
||
|
|
- `/workspaces/claude-marketplace/.sdlc-agents/` - Agent documentation directory
|
||
|
|
- `/workspaces/claude-marketplace/.sdlc-agents/setup.sh` - Agent setup script
|
||
|
|
|
||
|
|
## Verification
|
||
|
|
|
||
|
|
After generating the README.md:
|
||
|
|
|
||
|
|
1. Check markdown syntax (headings, lists, code blocks, tables)
|
||
|
|
2. Verify all internal links point to existing files
|
||
|
|
3. Ensure all referenced tools and scripts actually exist
|
||
|
|
4. Confirm information consistency with source files
|
||
|
|
5. Review for completeness: Does it answer "What is this repo?" and "How do I use it?"
|
||
|
|
|
||
|
|
## Success Criteria
|
||
|
|
|
||
|
|
- README.md exists at repository root
|
||
|
|
- Provides clear overview of both major components
|
||
|
|
- Includes practical usage examples
|
||
|
|
- Links to authoritative detailed documentation
|
||
|
|
- Follows standard GitHub README conventions
|
||
|
|
- New users can understand the project and get started
|