Skip to content

Commit 714428e

Browse files
Copilotjcmrs
Copilot
and
jcmrs
committed
Add comprehensive documentation for workflows and contributing
Co-authored-by: jcmrs <[email protected]>
1 parent 35a459b commit 714428e

File tree

4 files changed

+393
-0
lines changed

4 files changed

+393
-0
lines changed

‎.github/workflows/README.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# GitHub Actions Workflows
2+
3+
This document provides an overview of the automated workflows configured for this repository.
4+
5+
## Workflows Overview
6+
7+
### 1. Python Lint (`python-lint.yml`)
8+
9+
**Trigger:** Push or PR to main/develop branches with Python file changes
10+
**Status:** [![Python Lint](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/python-lint.yml/badge.svg)](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/python-lint.yml)
11+
12+
**Purpose:** Validates Python code quality and syntax in `spec-kit-partner/src/`
13+
14+
**Steps:**
15+
1. Checks syntax errors with flake8 (strict)
16+
2. Runs style checks with flake8 (warnings)
17+
3. Analyzes code quality with pylint (warnings)
18+
19+
**Configuration:**
20+
- Python version: 3.9
21+
- Max line length: 127 characters
22+
- Max complexity: 10
23+
24+
---
25+
26+
### 2. Validate Plugin Manifests (`validate-manifests.yml`)
27+
28+
**Trigger:** Push or PR to main/develop branches with manifest changes
29+
**Status:** [![Validate Manifests](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/validate-manifests.yml/badge.svg)](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/validate-manifests.yml)
30+
31+
**Purpose:** Ensures plugin manifests are valid and complete
32+
33+
**Steps:**
34+
1. Validates `.claude-plugin/plugin.json` exists and is valid JSON
35+
2. Validates `.claude-plugin/marketplace.json` exists and is valid JSON
36+
3. Checks required fields in `plugin.json`: `name`, `version`, `description`, `author`, `license`
37+
4. Checks required fields in `marketplace.json`: `display_name`, `summary`, `description`, `categories`, `icon`, `publisher`, `license`, `version`
38+
39+
---
40+
41+
### 3. Validate Referenced Assets (`validate-assets.yml`)
42+
43+
**Trigger:** Push or PR to main/develop branches with manifest or asset changes
44+
**Status:** [![Validate Assets](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/validate-assets.yml/badge.svg)](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/validate-assets.yml)
45+
46+
**Purpose:** Verifies all referenced assets exist in the repository
47+
48+
**Steps:**
49+
1. Checks icon exists (`assets/icon.png`)
50+
2. Checks README exists
51+
3. Validates all screenshots referenced in `marketplace.json` exist
52+
53+
---
54+
55+
### 4. Lint Markdown and Mermaid (`lint-markdown-mermaid.yml`)
56+
57+
**Trigger:** Push or PR to main/develop branches with Markdown or Mermaid changes
58+
**Status:** [![Lint Markdown and Mermaid](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/lint-markdown-mermaid.yml/badge.svg)](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/lint-markdown-mermaid.yml)
59+
60+
**Purpose:** Validates Markdown and Mermaid syntax (content is not validated)
61+
62+
**Steps:**
63+
1. Lints all Markdown files with markdownlint-cli (warnings only)
64+
2. Validates basic Mermaid diagram syntax
65+
66+
**Configuration:**
67+
- Markdown rules: See `.markdownlint.json`
68+
- Mermaid: Basic syntax validation only
69+
70+
---
71+
72+
### 5. Python Tests (`python-tests.yml`)
73+
74+
**Trigger:** Push or PR to main/develop branches with Python or test file changes
75+
**Status:** [![Python Tests](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/python-tests.yml/badge.svg)](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions/workflows/python-tests.yml)
76+
77+
**Purpose:** Runs automated tests to verify code functionality
78+
79+
**Steps:**
80+
1. Runs basic test suite (`tests/test_basic.py`)
81+
2. Runs pytest on all test files
82+
83+
**Test Coverage:**
84+
- Module import validation
85+
- Constants verification
86+
- Class existence checks
87+
- Basic functionality tests
88+
89+
---
90+
91+
## Workflow Status
92+
93+
All workflows must pass before a pull request can be merged. You can view the status of all workflows in the [Actions tab](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/actions).
94+
95+
## Local Testing
96+
97+
Before pushing code, run these commands locally to catch issues early:
98+
99+
```bash
100+
# Python linting
101+
flake8 spec-kit-partner/src --count --select=E9,F63,F7,F82 --show-source --statistics
102+
103+
# JSON validation
104+
python3 -m json.tool .claude-plugin/plugin.json > /dev/null
105+
python3 -m json.tool .claude-plugin/marketplace.json > /dev/null
106+
107+
# Tests
108+
python tests/test_basic.py
109+
110+
# Markdown linting
111+
markdownlint '**/*.md' --ignore node_modules
112+
```
113+
114+
## Troubleshooting
115+
116+
### Workflow Fails
117+
118+
1. **Check the workflow logs** in the Actions tab
119+
2. **Run checks locally** using the commands above
120+
3. **Fix issues** and commit the fixes
121+
4. **Re-run the workflow** - it will run automatically on the new commit
122+
123+
### Common Issues
124+
125+
- **JSON syntax errors**: Make sure JSON files have no trailing commas or comments
126+
- **Missing assets**: Ensure all referenced files exist in the repository
127+
- **Python syntax errors**: Run flake8 locally to identify issues
128+
- **Import errors**: Verify all module dependencies are available
129+
130+
## Adding New Workflows
131+
132+
To add a new workflow:
133+
134+
1. Create a new YAML file in `.github/workflows/`
135+
2. Follow the existing workflow structure
136+
3. Test locally before committing
137+
4. Update this documentation
138+
139+
See [GitHub Actions documentation](https://docs.github.com/en/actions) for more information.

‎CONTRIBUTING.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Contributing to Spec Kit Partner
2+
3+
Thank you for your interest in contributing to the Spec Kit Partner plugin! This document provides guidelines and information about our development workflows.
4+
5+
## Development Setup
6+
7+
1. **Clone the repository**
8+
```bash
9+
git clone https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin.git
10+
cd claude-code-spec-kit-subagent-plugin
11+
```
12+
13+
2. **Install Python dependencies**
14+
```bash
15+
pip install flake8 pylint pytest
16+
```
17+
18+
3. **Install Node.js tools (for Markdown linting)**
19+
```bash
20+
npm install -g markdownlint-cli
21+
```
22+
23+
## Automated Workflows
24+
25+
This repository uses GitHub Actions to automatically validate all contributions. The following workflows run on every push and pull request:
26+
27+
### 1. Python Linting (`python-lint.yml`)
28+
29+
**Purpose:** Ensures Python code in `spec-kit-partner/src/` follows syntax and style guidelines.
30+
31+
**Tools:**
32+
- **flake8** - Checks for syntax errors and undefined names (fails on errors)
33+
- **pylint** - Additional code quality checks (warnings only)
34+
35+
**Run locally:**
36+
```bash
37+
flake8 spec-kit-partner/src --count --select=E9,F63,F7,F82 --show-source --statistics
38+
flake8 spec-kit-partner/src --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
39+
pylint spec-kit-partner/src --exit-zero --max-line-length=127
40+
```
41+
42+
### 2. JSON Manifest Validation (`validate-manifests.yml`)
43+
44+
**Purpose:** Validates that plugin manifests exist, are valid JSON, and contain all required fields.
45+
46+
**Checks:**
47+
- `.claude-plugin/plugin.json` exists and is valid JSON
48+
- `.claude-plugin/marketplace.json` exists and is valid JSON
49+
- Required fields are present in both files
50+
51+
**Required fields in `plugin.json`:**
52+
- `name`, `version`, `description`, `author`, `license`
53+
54+
**Required fields in `marketplace.json`:**
55+
- `display_name`, `summary`, `description`, `categories`, `icon`, `publisher`, `license`, `version`
56+
57+
**Run locally:**
58+
```bash
59+
python3 -m json.tool .claude-plugin/plugin.json > /dev/null
60+
python3 -m json.tool .claude-plugin/marketplace.json > /dev/null
61+
```
62+
63+
### 3. Asset Validation (`validate-assets.yml`)
64+
65+
**Purpose:** Ensures all assets referenced in manifests actually exist in the repository.
66+
67+
**Checks:**
68+
- Icon file exists (`assets/icon.png`)
69+
- README file exists (`README.md`)
70+
- Screenshot files exist (as listed in `marketplace.json`)
71+
72+
**Run locally:**
73+
```bash
74+
# Check if referenced assets exist
75+
test -f assets/icon.png && echo "✓ Icon found"
76+
test -f README.md && echo "✓ README found"
77+
test -f assets/screenshot1.png && echo "✓ Screenshot 1 found"
78+
test -f assets/screenshot2.png && echo "✓ Screenshot 2 found"
79+
```
80+
81+
### 4. Markdown and Mermaid Linting (`lint-markdown-mermaid.yml`)
82+
83+
**Purpose:** Validates Markdown syntax and Mermaid diagram syntax (not content completeness).
84+
85+
**Tools:**
86+
- **markdownlint-cli** - Checks Markdown formatting (warnings only)
87+
- **Python validator** - Basic Mermaid syntax validation
88+
89+
**Run locally:**
90+
```bash
91+
# Lint Markdown
92+
markdownlint '**/*.md' --ignore node_modules
93+
94+
# Validate Mermaid diagrams
95+
find . -name "*.mermaid" -o -name "*.mmd"
96+
```
97+
98+
### 5. Python Tests (`python-tests.yml`)
99+
100+
**Purpose:** Runs automated tests to verify Python code functionality.
101+
102+
**Current tests:**
103+
- Module import validation
104+
- Constants and class existence checks
105+
- Basic functionality tests
106+
107+
**Run locally:**
108+
```bash
109+
python tests/test_basic.py
110+
pytest tests/ -v
111+
```
112+
113+
## Pull Request Process
114+
115+
1. **Fork and create a branch**
116+
```bash
117+
git checkout -b feature/your-feature-name
118+
```
119+
120+
2. **Make your changes**
121+
- Follow existing code style
122+
- Keep changes minimal and focused
123+
- Update documentation as needed
124+
125+
3. **Test locally**
126+
```bash
127+
# Run linting
128+
flake8 spec-kit-partner/src
129+
130+
# Run tests
131+
python tests/test_basic.py
132+
133+
# Validate JSON
134+
python3 -m json.tool .claude-plugin/plugin.json > /dev/null
135+
```
136+
137+
4. **Commit and push**
138+
```bash
139+
git add .
140+
git commit -m "Description of your changes"
141+
git push origin feature/your-feature-name
142+
```
143+
144+
5. **Create Pull Request**
145+
- All workflows must pass before merging
146+
- Request review from maintainers
147+
- Address any feedback
148+
149+
## Code Style Guidelines
150+
151+
### Python
152+
- Maximum line length: 127 characters
153+
- Use PEP 8 style guide
154+
- Add docstrings to functions and classes
155+
- Keep complexity reasonable (max-complexity=10)
156+
157+
### Markdown
158+
- Use consistent heading levels
159+
- Include blank lines around code blocks and lists
160+
- Keep line length reasonable (no strict limit)
161+
162+
### JSON
163+
- Use 2-space indentation
164+
- No trailing commas
165+
- No comments (JSON doesn't support them)
166+
167+
## File Structure
168+
169+
```
170+
claude-code-spec-kit-subagent-plugin/
171+
├── .github/workflows/ # GitHub Actions workflows
172+
├── .claude-plugin/ # Plugin manifests
173+
├── agents/ # Agent documentation
174+
├── assets/ # Images and static files
175+
├── spec-kit-partner/
176+
│ ├── src/ # Python source code
177+
│ ├── project-data/ # Runtime data files
178+
│ ├── diagrams/ # Mermaid diagrams
179+
│ └── spec/ # Specification files
180+
└── tests/ # Test files
181+
```
182+
183+
## Adding New Workflows
184+
185+
If you need to add a new workflow:
186+
187+
1. Create a new YAML file in `.github/workflows/`
188+
2. Follow the existing workflow structure
189+
3. Test locally before committing
190+
4. Document the workflow in this file
191+
192+
## Questions?
193+
194+
- Open an issue: [GitHub Issues](https://github.com/jcmrs/claude-code-spec-kit-subagent-plugin/issues)
195+
- Check the [README](./README.md) for general information
196+
- Review the [ROADMAP](./ROADMAP.md) for planned features
197+
198+
## License
199+
200+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,20 @@ See [spec-kit-partner.md](./agents/spec-kit-partner.md) for full protocol.
102102

103103
---
104104

105+
## Development & Contributing
106+
107+
This repository includes automated workflows to ensure code quality:
108+
109+
- **Python Linting** - Validates syntax and style of Python code
110+
- **JSON Validation** - Ensures plugin manifests are valid and complete
111+
- **Asset Validation** - Checks that referenced files exist
112+
- **Markdown/Mermaid Linting** - Validates documentation syntax
113+
- **Python Tests** - Runs automated test suite
114+
115+
All workflows run automatically on pull requests. See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed development guidelines.
116+
117+
---
118+
105119
## License
106120

107121
This project is licensed under the [MIT License](./LICENSE).

0 commit comments

Comments
 (0)