Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
186 lines (123 loc) · 5.54 KB

CONTRIBUTING.md

File metadata and controls

186 lines (123 loc) · 5.54 KB

Contributing to Smart SDLC

Thank you for your interest in contributing! Smart SDLC is a community-driven framework — contributions to skills, integrations, documentation, and tooling are all welcome.

Ways to Contribute

Type Examples
New skills Additional workflow skills, new integration skills, utility skills
Improve existing skills Better instructions, clearer steps, edge case handling
Integrations New system integrations (Linear, Notion, ServiceNow, etc.)
CLI commands New bin/ commands or enhancements to existing ones
Documentation Corrections, examples, guides, translations
Bug reports Unexpected AI behaviour, skill logic errors, CLI issues

Getting Started

1. Fork and clone

git clone https://github.com/supermldev/smart-sdlc.git
cd smart-sdlc

2. Install

No dependencies — but make sure you're on Node.js 16+:

node --version   # >= 16

3. Run locally

node bin/superml.js help
node bin/superml.js init

Or link globally to test npx-style:

npm link
smart-sdlc help

Skill Contributions

Skills are the core of Smart SDLC. A skill is a SKILL.md file with YAML frontmatter and structured AI instructions.

Skill file format

---
skill: your-skill-name
title: "Human-readable title"
phase: "0-relearn | 1-analysis | 2-planning | 3-solutioning | 4-implementation | 5-modernize | core | integrations"
persona: "all | product | architect | developer | modernization | team_lead"
type: "workflow | utility | integration | agent"
---

## Skill: Your Skill Name

Brief description of what this skill does and when to use it.

## Activation

...

## Instructions for the AI

...

Skill placement

skills/
├── 0-relearn/         # Brownfield onboarding, codebase exploration
├── 1-analysis/        # Problem analysis, research
├── 2-planning/        # PRDs, requirements, UX
├── 3-solutioning/     # Architecture, stories, context
├── 4-implementation/  # Coding, review, sprint
├── 5-modernize/       # Legacy analysis, migration
├── core/              # Utilities available to all personas
└── integrations/      # External system connections

Each skill lives in its own folder: skills/<phase>/<skill-name>/SKILL.md.

Multi-step workflows can include a workflow.md and a steps/ subdirectory with numbered step files.

Registering a new skill

After adding the SKILL.md, register it in lib/commands/init.js:

  1. Add the skill path to SKILL_PERSONA_ACCESS — use null for unrestricted or a persona name to restrict access:

    'integrations/your-skill/action': null,          // all personas
'integrations/your-skill/action': 'developer',   // developer only

  2. If it's an integration with a connect step, add it to the INTEGRATIONS array in init.js.

Integration Contributions

New integrations follow the same pattern as existing ones in skills/integrations/. Each integration should include:

  • connect/SKILL.md — set up and verify connectivity; support both REST and MCP modes if applicable
  • Action skills (e.g. create-story/SKILL.md, sync/SKILL.md, push-doc/SKILL.md)

If the integration supports MCP, follow the pattern in skills/integrations/jira/connect/SKILL.md — offer REST vs MCP path, generate .vscode/mcp.json entries, and write connection_mode to _superml/config.yml.

Pull Request Guidelines

  1. One feature or fix per PR — keep changes focused and reviewable
  2. Test your skill manually — open GitHub Copilot Chat, attach your SKILL.md, and run through the workflow. Note the result in the PR description
  3. No breaking changes to existing config keys — additive changes only; deprecate with a comment if a key needs renaming
  4. Update docs if needed — if you add a skill, add a row to docs/skills-reference.md; if you add an integration, update docs/integrations.md
  5. Commit messages — use Conventional Commits: feat:, fix:, docs:, refactor:, chore:

PR description template

## What this adds / fixes

Brief description.

## Skill / command affected

e.g. `skills/integrations/linear/connect/SKILL.md`, `lib/commands/init.js`

## Manual test

- Opened Copilot Chat, ran `/sml-your-skill`
- Step 1: [what happened]
- Step 2: [what happened]
- Result: [outcome]

## Checklist
- [ ] SKILL.md follows the standard frontmatter format
- [ ] Skill registered in `SKILL_PERSONA_ACCESS` in `init.js`
- [ ] `docs/skills-reference.md` updated (if new skill)
- [ ] `docs/integrations.md` updated (if new integration)
- [ ] No credentials or tokens hardcoded anywhere

Reporting Issues

Open a GitHub Issue with:

  • Smart SDLC version: npx @supermldev/smart-sdlc --version
  • AI assistant: GitHub Copilot / Claude / Cursor / other
  • Skill or command: which skill or CLI command is affected
  • What happened vs what was expected
  • Config snippet (redact any tokens): relevant section of _superml/config.yml

Community

Join the Smart SDLC Discord for questions, ideas, and real-time discussion with maintainers and other contributors:

discord.gg/26XMXkEt

Code of Conduct

Be respectful, collaborative, and constructive. We follow the Contributor Covenant. By participating you agree to abide by its terms.

License

By contributing, you agree that your contributions will be licensed under the MIT License.