software-methodology

A comprehensive software development methodology from product strategy through production deployment. Eleven skills, each with a clear scope and a defined position in the chain. Together they form a closed loop: the last skill (continuous-improvement) feeds findings back into any skill upstream.

Works with:

• 🤖 Claude Desktop (via MCP server) — Structured tools for querying methodology
• 🔮 GitHub Copilot (via .github/copilot-instructions.md) — AI-guided methodology navigation
• 📝 VS Code — Direct markdown file access and workspace navigation
• 🎯 Claude Code — Deployable .skill files for autonomous coding
• 🛡️ atdd-guardian (via git hooks & CI/CD) — Workflow enforcement and validation

Quick Start: See docs/QUICKSTART.md | Skills Index: docs/SKILLS.md | MCP Server: mcp-server/QUICKSTART.md | Sharing Guide: docs/SHARING.md

Installation

npm install @schilling.mark.a/software-methodology

Or clone from source:

git clone https://github.com/MarkSchilling/software-methodology.git

The Chain

Skills execute in this order. Two skills (marked with *) are references consulted during other steps rather than executed sequentially.

product-strategy        →  Business Model Canvas and Value Proposition Canvas
ux-research             →  Personas, mental models, user journey maps
story-mapping           →  Backbone activities, tasks, release sequencing
bdd-specification       →  Gherkin feature files via example mapping
ux-design               →  Information architecture, interaction patterns, usability evaluation, onboarding
ui-design-workflow      →  Screen flows, component selection, acceptance targets
ui-design-system     *  →  Design tokens, typography, layout, components, accessibility
atdd-workflow           →  RED-GREEN-REFACTOR implementation driven by acceptance tests
clean-code           *  →  SOLID principles and design patterns
cicd-pipeline           →  Pipeline stages, environment promotion, deployment and rollback
continuous-improvement  →  Measurement, root cause analysis, process updates (feeds back upstream)

ui-design-system is consulted by ui-design-workflow. clean-code is consulted by atdd-workflow during GREEN and REFACTOR phases.

Repo Structure

software-methodology/
├── dist/                       ← Packaged .skill files (these are what you deploy)
│   ├── product-strategy.skill
│   ├── ux-research.skill
│   └── ...
├── product-strategy/           ← Source for each skill
│   ├── SKILL.md                ← Entry point: triggers, workflow, decision routing
│   └── references/             ← Detail files, loaded on demand
│       ├── business-model-canvas.md
│       └── ...
├── ux-research/
├── story-mapping/
├── ...
└── project-templates/          ← Starting templates for new projects
    ├── context.md.template     ← The file Claude Code reads at session start
    └── test-strategy.md.template

.skill files are zip archives with a different extension — that is the format Claude expects. They will appear empty or opaque in most file browsers and editors. If you need to inspect the contents of one, rename it to .zip and extract it, or run unzip -l <file>.skill to list its contents. The human-readable source for every skill lives in the named directories alongside dist/ — that is where you read and edit.

Each skill follows the same internal structure. SKILL.md is the entry point — it defines when the skill runs, routes to the relevant reference file, and stays under ~75 lines. All detail lives in references/. This keeps each skill's cognitive load low: Claude reads SKILL.md, then loads only the one reference it needs.

Usage

The methodology supports multiple AI coding assistants. Choose the approach that fits your workflow:

Using with Claude Code

1. Deploy the skills.

Copy the .skill files from dist/ into your project's skill directory:

/mnt/skills/user/product-strategy.skill
/mnt/skills/user/ux-research.skill
/mnt/skills/user/story-mapping.skill
...

2. Bootstrap your project.

Create two files in your project's /docs/ directory from the templates in project-templates/:

• context.md — tells Claude Code which skills are available and where to find project documents. Fill in the project-specific sections (name, tech stack, architecture).
• test-strategy.md — defines the testing tools, commands, and coverage thresholds for your project. atdd-workflow and cicd-pipeline both read this.

3. Start with product-strategy.

Before any other skill runs, create the Business Model Canvas and Value Proposition Canvas. Every downstream skill reads from these. Nothing else can start without them.

4. Follow the chain.

Each skill's SKILL.md tells you what to read before starting and what it produces. The chain is the workflow. Run skills in order for a new product. Jump to the relevant skill when iterating on an existing one.

Using with GitHub Copilot / VS Code

1. Install the methodology.

Choose one of these installation methods:

# Option 1: Install via npm (recommended)
npm install @schilling.mark.a/software-methodology

# Option 2: Add as a submodule
git submodule add https://github.com/MarkSchilling/software-methodology.git methodology

# Option 3: Clone separately
git clone https://github.com/MarkSchilling/software-methodology.git

2. GitHub Copilot reads the instructions automatically.

The .github/copilot-instructions.md file tells Copilot how to use the skills. Copilot will:

• Suggest which skill applies to your current task
• Reference the appropriate SKILL.md and reference files
• Guide you through the methodology chain

3. Use the Skills Index for navigation.

Open docs/SKILLS.md for a complete index with links to all skills and their references. This provides quick navigation to any skill's documentation.

4. Optional: Open the workspace in VS Code.

For enhanced navigation with folder organization:

code .vscode/software-methodology.code-workspace

This opens a multi-folder workspace with each skill organized and labeled with emojis for easy identification.

5. Ask Copilot for methodology guidance.

In VS Code or GitHub, ask Copilot questions like:

• "Which skill should I use for writing feature specifications?"
• "How do I implement the RED-GREEN-REFACTOR cycle?"
• "What design patterns should I consider?"

Copilot will reference the appropriate skill files and guide you through the process.

Using with Claude Desktop (MCP Server)

1. Install the methodology and build the MCP server.

# Option 1: Install via npm (recommended)
npm install @schilling.mark.a/software-methodology
cd node_modules/@schilling.mark.a/software-methodology/mcp-server
npm install
npm run build

# Option 2: Clone and build from source
git clone https://github.com/MarkSchilling/software-methodology.git
cd software-methodology/mcp-server
npm install
npm run build

2. Configure Claude Desktop.

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the MCP server (use the path matching your installation method):

{
  "mcpServers": {
    "software-methodology": {
      "command": "node",
      "args": [
        "/absolute/path/to/node_modules/@schilling.mark.a/software-methodology/mcp-server/dist/index.js"
      ]
    }
  }
}

Note: If you cloned from source, use the path to your clone instead:

"/absolute/path/to/software-methodology/mcp-server/dist/index.js"

3. Restart Claude Desktop.

The MCP server will start automatically and provide structured access to the methodology.

4. Use the MCP tools.

In Claude Desktop, ask questions like:

• "List all available skills"
• "Show me the SOLID principles"
• "What are the pains for Individual Developer?"
• "What should I do next?" (analyzes your project state)
• "Search for test-first guidance"
• "Validate this Gherkin scenario" (checks against best practices)

See mcp-server/QUICKSTART.md for detailed setup and troubleshooting.

Using with atdd-guardian (Workflow Enforcement)

atdd-guardian is a complementary tool that enforces the methodology, while software-methodology MCP guides you through it. Think of software-methodology as knowledge and atdd-guardian as guardrails.

Complementary Roles:

| Tool | Role | How It Helps | |------|------|--------------| | software-methodology MCP | Knowledge & Guidance | Reads skills, queries VPC, suggests next steps, validates Gherkin syntax | | atdd-guardian | Workflow Enforcement | Blocks invalid commits, enforces RED-GREEN-REFACTOR, checks test coverage, validates commit messages |

1. Install atdd-guardian.

Clone the repository and follow its setup instructions:

git clone https://github.com/MarkSchilling/atdd-guardian.git
cd atdd-guardian
# Follow installation instructions in atdd-guardian/README.md

2. Typical workflow using both tools.

# 1. Use software-methodology MCP in Claude Desktop to plan
#    "What should I do next?"
#    → Suggests: "Write Gherkin scenario for user login"

# 2. Write the scenario
vim features/authentication.feature

# 3. Use MCP to validate syntax
#    "Validate this Gherkin scenario"
#    → Returns validation feedback

# 4. Try to commit (atdd-guardian enforces RED phase)
git add features/authentication.feature
git commit -m "Add login scenario"
# ✅ Passes: Gherkin scenarios can be committed before tests

# 5. Write failing test (RED phase)
vim tests/authentication.test.ts

# 6. Try to commit without running tests (atdd-guardian blocks)
git add tests/authentication.test.ts
git commit -m "RED: Add login test"
# ❌ Blocked: "Tests must pass before committing RED phase"

# 7. Run tests, verify failure, commit
npm test  # Fails as expected
git commit -m "RED: Add login test - FAILING as expected"
# ✅ Passes: RED commit with failing test documented

# 8. Implement feature (GREEN phase)
vim src/auth/login.ts

# 9. Try to commit without tests passing (atdd-guardian blocks)
git add src/auth/login.ts
git commit -m "GREEN: Implement login"
# ❌ Blocked: "Tests must pass in GREEN phase"

# 10. Fix implementation, run tests, commit
npm test  # Now passes
git commit -m "GREEN: Implement login - tests passing"
# ✅ Passes: GREEN commit with passing tests

# 11. Use MCP for refactoring guidance
#     "Search for guidance on dependency injection"
#     → Returns clean-code references

# 12. Refactor (atdd-guardian requires tests stay green)
vim src/auth/login.ts
npm test  # Must still pass
git commit -m "REFACTOR: Extract authentication service"
# ✅ Passes: REFACTOR with tests still passing

3. How they work together.

• software-methodology MCP: Answers "What should I do?" and "Is this right?" — provides methodology knowledge
• atdd-guardian: Enforces "You must follow the rules" — prevents workflow violations

Both tools reference the same methodology, creating a complete system: one guides you forward, the other prevents you from going backward.

General Workflow (All Tools)

1. Start with product-strategy — Create Business Model Canvas and Value Proposition Canvas
2. Follow the chain — Each skill's SKILL.md defines prerequisites and outputs
3. Use reference skills — ui-design-system and clean-code are consulted during other steps
4. Close the loop — continuous-improvement feeds insights back to upstream skills

Contributing

Editing a skill: Edit the source directory (e.g., product-strategy/references/business-model-canvas.md). Never edit .skill files in dist/ directly — they are build outputs.

Repackaging after an edit:

python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py <skill-dir> dist/

Example:

python3 /mnt/skills/examples/skill-creator/scripts/package_skill.py product-strategy/ dist/

The packager validates the skill structure before producing the .skill file. If validation fails, it will tell you what is wrong.

Adding a new skill: Follow the same pattern as existing skills. Run the init script to scaffold:

python3 /mnt/skills/examples/skill-creator/scripts/init_skill.py <skill-name> --path .

Then write SKILL.md and populate references/. The SKILL.md should define: when this skill triggers, what it produces, and how it connects to the rest of the chain. Keep SKILL.md under ~75 lines. Put all detail in references.

Process updates from continuous-improvement: When continuous-improvement identifies a gap in a skill, the fix is an edit to that skill's source. Commit it the same way as any other change. The validation criterion from the root cause analysis goes in the commit message.

Sharing and Distribution

Want to share these skills with your team, organization, or community? See the Sharing Guide for comprehensive recommendations on:

• Distribution channels — GitHub, NPM, PyPI, VS Code extensions, documentation sites, Docker
• Target audiences — Individual developers, teams, enterprises, consultants, students
• Use case examples — Quick starts, team adoption, enterprise standardization, training
• Community contribution — How to report issues, suggest improvements, and submit changes

The methodology is designed to be shared and adapted. Choose the distribution method that fits your needs.