swe-workflow-skills 0.1.0

package/skills/prd-writing/templates/prd.md

@@ -0,0 +1,71 @@
+# Agile PRD Template
+
+```markdown
+# PRD: [Feature/Product Name]
+
+**Author**: [Name]
+**Date**: [YYYY-MM-DD]
+**Status**: Draft | In Review | Approved
+**Target release**: [Sprint/Quarter/Date]
+
+## Problem
+
+[What problem are we solving? Who has it? How do we know it's real?
+Include data: user feedback, support tickets, analytics, competitive pressure.]
+
+## Goals
+
+1. [Measurable goal tied to a metric]
+2. [Measurable goal tied to a metric]
+
+## Non-Goals
+
+- [What this project explicitly will NOT do]
+- [Scope boundaries that prevent creep]
+
+## User Stories
+
+### Must Have
+- As a [persona], I want to [action] so that [benefit]
+  - AC: [Given/When/Then acceptance criteria]
+- As a [persona], I want to [action] so that [benefit]
+  - AC: [Acceptance criteria]
+
+### Should Have
+- As a [persona], I want to [action] so that [benefit]
+
+### Could Have
+- As a [persona], I want to [action] so that [benefit]
+
+### Won't Have (this time)
+- [Explicitly deferred features — important for setting expectations]
+
+## User Experience
+
+[Description of the intended experience, or links to mockups/wireframes.
+Enough for a designer to start, not a pixel-perfect spec.]
+
+## Constraints
+
+- **Performance**: [e.g., Page load under 2s]
+- **Compatibility**: [e.g., Support latest 2 versions of Chrome, Firefox, Safari]
+- **Accessibility**: [e.g., WCAG 2.1 AA compliance]
+- **Regulatory**: [e.g., GDPR data handling requirements]
+
+## Success Metrics
+
+| Metric | Current | Target | How Measured |
+|--------|---------|--------|--------------|
+| [Metric] | [Baseline] | [Goal] | [Tool/method] |
+
+## Open Questions
+
+- [ ] [Question that needs answering before or during implementation]
+
+## References
+
+- [Design mockups link]
+- [User research link]
+- [Competitive analysis link]
+- [Related PRDs or RFCs]
+```

package/skills/prd-writing/templates/rfc.md

@@ -0,0 +1,79 @@
+# Technical RFC Template
+
+```markdown
+# RFC: [Title]
+
+**Author**: [Name]
+**Date**: [YYYY-MM-DD]
+**Status**: Draft | In Review | Accepted | Rejected | Superseded
+**Review deadline**: [Date — give reviewers a clear deadline]
+**Reviewers**: [Names/teams]
+
+## Context
+
+[What triggered this RFC? What's the current state? What constraints exist?
+Provide enough context for a reviewer who isn't working on this daily.]
+
+## Problem
+
+[Specific technical problem to solve. Reference the PRD if one exists.]
+
+## Proposed Solution
+
+[Describe the technical approach. Include diagrams where helpful.
+This should be detailed enough that an engineer can implement from it,
+but not so detailed that it prescribes every function signature.]
+
+### Architecture / Design
+
+[High-level design, component diagram, data flow]
+
+### Data Model Changes
+
+[New tables, modified columns, migrations needed.
+Link to data-modeling skill output if applicable.]
+
+### API Changes
+
+[New or modified endpoints.
+Link to api-design skill output if applicable.]
+
+### Migration Plan
+
+[How to get from current state to proposed state safely.
+Especially important for production changes.]
+
+## Alternatives Considered
+
+### [Alternative A]
+[Description]
+**Why not**: [Specific reason this approach was rejected]
+
+### [Alternative B]
+[Description]
+**Why not**: [Specific reason]
+
+## Risks and Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| [Risk] | [Strategy] |
+
+## Open Questions
+
+- [ ] [Question for reviewers]
+- [ ] [Decision that needs input]
+
+## Implementation Plan
+
+[Rough phases. Link to feature-planning output for detailed task breakdown.]
+
+1. [Phase 1]: [What and rough timing]
+2. [Phase 2]: [What and rough timing]
+
+## References
+
+- [PRD link]
+- [Related ADRs]
+- [External documentation]
+```

package/skills/project-documentation/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: project-documentation
+description: "Write and maintain project docs — README, contributing guides, API docs, changelogs, inline docs. Triggers: write a README, document this project, create documentation, contributing guide, changelog, API docs, how do I document, this needs docs, onboarding docs, JSDoc, docstrings."
+model: haiku
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Project Documentation
+
+Help create and maintain documentation that makes a project understandable, usable, and contributable. Good documentation answers three questions: What is this? How do I use it? How do I contribute?
+
+## Document Types
+
+Identify which documents the project needs based on context:
+
+| Document | When Needed | Audience |
+|----------|-------------|----------|
+| README.md | Every project | Users, contributors, evaluators |
+| CONTRIBUTING.md | Open source or team > 3 | New contributors |
+| API Documentation | Any project with an API | API consumers |
+| CHANGELOG.md | Any project with releases | Users upgrading between versions |
+| Architecture docs | Complex systems | New team members, future maintainers |
+| Inline docs (JSDoc/docstrings) | Public APIs, complex logic | Developers reading the code |
+
+Ask the user which they need. If unsure, start with README — every project needs one.
+
+## Workflow: README
+
+### Step 1: Analyze the Project
+
+Before writing, understand what exists:
+
+- Read the codebase structure, package.json/pyproject.toml/go.mod, and existing docs
+- Identify the project type (library, CLI, web app, API, monorepo)
+- Identify the tech stack and key dependencies
+- Look for existing setup scripts, Docker files, or CI config
+- Check for a license file
+
+### Step 2: Write the README
+
+Use the template at [templates/readme.md](templates/readme.md). Adapt sections based on project type:
+
+**For a library/package**: Emphasize installation, quick start, API reference, and examples.
+**For a web app**: Emphasize prerequisites, setup, running locally, and environment config.
+**For a CLI tool**: Emphasize installation, usage with command examples, and configuration options.
+**For an API**: Emphasize endpoints overview, authentication, and link to full API docs.
+**For a monorepo**: Emphasize structure overview, per-package docs, and how packages relate.
+
+Key principles:
+- **Lead with value**: The first thing someone reads should explain what the project does and why they should care. Not the tech stack, not the folder structure.
+- **Working examples**: Every code snippet should be copy-pasteable and actually work.
+- **Prerequisites explicitly stated**: Don't assume Node 20, Python 3.12, or Docker are installed. State versions.
+- **From zero to running**: A new developer should go from `git clone` to a working local instance by following the README, without asking anyone.
+
+### Step 3: Verify
+
+- [ ] Can someone who has never seen this project understand what it does from the first paragraph?
+- [ ] Are all setup steps complete and in order?
+- [ ] Do code examples actually work?
+- [ ] Are prerequisites and versions specified?
+- [ ] Is there a way to verify the setup worked (e.g., "you should see X")?
+
+## Workflow: CONTRIBUTING.md
+
+See [references/contributing-guide.md](references/contributing-guide.md) for the full guide on writing contributing docs.
+
+## Workflow: API Documentation
+
+When documenting an API:
+
+1. **Inventory endpoints**: List all routes from the codebase (read router files)
+2. **For each endpoint**: Method, path, description, request params/body, response shape, error codes, auth requirements
+3. **Group by resource**: `/users/*`, `/orders/*`, `/products/*`
+4. **Include examples**: Real request/response pairs, including error responses
+5. **Output format**: Markdown for simple APIs, OpenAPI/Swagger spec for complex ones
+
+Suggest using the `api-design` skill if the API doesn't exist yet and needs designing.
+
+## Workflow: CHANGELOG
+
+Follow Keep a Changelog conventions:
+
+- Group changes under: Added, Changed, Deprecated, Removed, Fixed, Security
+- Newest version at the top
+- Link version headers to git comparison URLs
+- Write entries from the user's perspective, not the developer's
+
+See [templates/changelog.md](templates/changelog.md) for the format.
+
+## Workflow: Inline Documentation
+
+For code-level documentation (JSDoc, Python docstrings, Go doc comments):
+
+- **Document public APIs**: Every exported function, class, and type
+- **Skip obvious code**: Don't document `getName()` returning a name
+- **Document the why**: Why this approach, why this parameter exists, why this edge case matters
+- **Include examples** for non-obvious usage
+- **Document exceptions/errors**: What can go wrong and under what conditions
+
+## Principles Applied
+
+- **KISS**: Write the minimum documentation that makes the project usable. Don't over-document internals.
+- **DRY**: Don't duplicate information across docs. Link between documents instead.
+- **YAGNI**: Don't write architecture docs for a 200-line script. Match documentation depth to project complexity.

package/skills/project-documentation/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "skill_name": "project-documentation",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write a README for my project. It's a Node.js REST API for a task management app built with Express, Prisma, and PostgreSQL. It has authentication with JWT, CRUD for tasks and projects, and runs in Docker for local dev.",
+      "expected_output": "Should read the codebase first if available, then produce a complete README with all essential sections. Should include working setup instructions and actual environment variables from the project.",
+      "assertions": [
+        "Reads codebase/package.json before writing if available",
+        "Starts with a clear one-line description of what the project does",
+        "Includes prerequisites with specific versions",
+        "Setup instructions go from git clone to running server",
+        "Includes Docker setup instructions",
+        "Lists environment variables needed with descriptions",
+        "Includes verification step (e.g., 'visit localhost:3000/health')",
+        "Code examples are copy-pasteable",
+        "Saves the README.md file to the project root"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need to document the API endpoints of my Express app. We have about 15 endpoints across users, tasks, and projects resources.",
+      "expected_output": "Should read the route files, then produce organized API documentation grouped by resource with request/response examples.",
+      "assertions": [
+        "Reads the actual route/controller files to discover endpoints",
+        "Groups endpoints by resource (users, tasks, projects)",
+        "Documents method, path, description for each endpoint",
+        "Includes request body schema for POST/PUT endpoints",
+        "Includes response shape examples",
+        "Documents error responses (400, 401, 404)",
+        "Notes authentication requirements per endpoint"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Generate a changelog from our recent git history. We're about to release v2.1.0.",
+      "expected_output": "Should read git log, categorize commits into Added/Changed/Fixed/etc., and produce a Keep a Changelog formatted entry.",
+      "assertions": [
+        "Reads git log to find changes since last tag/release",
+        "Categorizes changes into Keep a Changelog sections",
+        "Writes entries from user perspective, not developer perspective",
+        "Includes the version number and date",
+        "Includes comparison link to previous version",
+        "Does not include trivial commits (merge commits, typo fixes) unless relevant"
+      ]
+    }
+  ]
+}

package/skills/project-documentation/references/contributing-guide.md

@@ -0,0 +1,100 @@
+# Writing a Contributing Guide
+
+## Contents
+- What to include
+- Template structure
+- Common mistakes
+
+## What to Include
+
+A CONTRIBUTING.md answers: "I want to help — how do I start?"
+
+It should cover:
+
+1. **How to set up the development environment** — complete, from-scratch instructions
+2. **How to run the project locally** — including any seed data, test accounts, etc.
+3. **How to run tests** — and what's expected to pass before submitting
+4. **Code conventions** — style guide, linting, formatting expectations
+5. **Branching and commit conventions** — branch naming, commit message format
+6. **How to submit a change** — PR process, review expectations, CI requirements
+7. **Where to ask questions** — Slack channel, GitHub discussions, issue templates
+
+## Template Structure
+
+```markdown
+# Contributing to [Project Name]
+
+Thanks for your interest in contributing! This guide will help you get started.
+
+## Development Setup
+
+### Prerequisites
+- [List all tools and versions]
+
+### Getting Started
+```bash
+# Step-by-step from clone to running
+```
+
+### Verifying Your Setup
+[How to confirm everything is working — specific expected output]
+
+## Making Changes
+
+### Branch Naming
+- `feat/short-description` — new features
+- `fix/short-description` — bug fixes
+- `docs/short-description` — documentation only
+- `refactor/short-description` — code improvements
+
+### Commit Messages
+[Format and conventions — reference git-workflow skill]
+
+### Code Style
+- [Linting tool and config]
+- [Formatting tool and config]
+- Run `npm run lint` before committing
+
+### Testing
+- Write tests for new functionality
+- Ensure all existing tests pass: `npm test`
+- Add integration tests for API changes
+
+## Submitting a Pull Request
+
+1. Fork the repository and create your branch from `main`
+2. Make your changes with tests
+3. Ensure the test suite passes
+4. Update documentation if needed
+5. Submit a PR with a clear description of the changes
+
+### PR Description Template
+- **What**: What this PR does
+- **Why**: Why this change is needed
+- **How**: Brief description of the approach
+- **Testing**: How you tested the changes
+
+### Review Process
+- PRs require [N] approving reviews
+- CI must pass before merge
+- Maintainers may request changes — this is normal and collaborative
+
+## Reporting Bugs
+
+Use the GitHub issue template. Include:
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+- Environment (OS, Node version, etc.)
+
+## Questions?
+
+[Where to reach the team for help]
+```
+
+## Common Mistakes
+
+- **Assuming knowledge**: Don't assume contributors know your stack. A Python developer might want to contribute to your TypeScript project.
+- **Outdated setup instructions**: These go stale fast. Run through them periodically on a clean machine.
+- **Missing the "verify" step**: After setup, how does the contributor know it worked? Give them a specific command and expected output.
+- **No mention of the PR process**: Contributors submit code and then wonder what happens next. Be explicit about review timelines and expectations.

package/skills/project-documentation/templates/changelog.md

@@ -0,0 +1,59 @@
+# Changelog Template
+
+Follow the Keep a Changelog convention (keepachangelog.com).
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- [Description of new feature from user perspective]
+
+### Changed
+- [Description of changed behavior]
+
+### Fixed
+- [Description of bug fix, ideally referencing the issue]
+
+## [1.2.0] - 2025-03-01
+
+### Added
+- User notification preferences with email and in-app options (#123)
+- Rate limiting on public API endpoints (#130)
+
+### Changed
+- Improved error messages for authentication failures (#128)
+
+### Fixed
+- Order total calculation now correctly applies percentage discounts (#125)
+- Fixed timezone handling in scheduled report generation (#127)
+
+### Security
+- Updated dependency `some-lib` to patch CVE-2025-XXXX (#131)
+
+## [1.1.0] - 2025-02-15
+
+### Added
+- Webhook support for order status changes
+
+### Deprecated
+- `GET /api/v1/orders/status` — use `GET /api/v2/orders/:id/status` instead
+
+[Unreleased]: https://github.com/org/project/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/org/project/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/org/project/releases/tag/v1.1.0
+```
+
+## Writing Good Entries
+
+- **Write for users, not developers**: "Added dark mode" not "Added ThemeProvider with CSS variable injection"
+- **Reference issues/PRs**: Include the number so readers can find context
+- **Be specific**: "Fixed login failing when email contains a plus sign" not "Fixed login bug"
+- **One entry per change**: Don't bundle multiple changes into one bullet
+- **Use past tense or imperative**: Be consistent throughout

package/skills/project-documentation/templates/readme.md

@@ -0,0 +1,121 @@
+# README Template
+
+Adapt this template based on project type. Remove sections that don't apply. Every section should earn its place — if it doesn't help the reader use or understand the project, cut it.
+
+```markdown
+# Project Name
+
+[One-line description: what this does and why someone would use it.]
+
+[Optional: badges for build status, coverage, npm version, license]
+
+## Overview
+
+[2-4 sentences expanding on the one-liner. What problem does it solve? Who is it for?
+Include a screenshot, GIF, or terminal recording if visual.]
+
+## Quick Start
+
+[The fastest path from zero to working. Should be 3-5 steps maximum.]
+
+```bash
+# Install
+npm install project-name
+
+# Basic usage
+import { thing } from 'project-name';
+const result = thing('input');
+```
+
+## Prerequisites
+
+[Only list what's NOT obvious. If it's a Node.js project, listing Node is expected.]
+
+- Node.js >= 18
+- PostgreSQL >= 14
+- Docker (for local development)
+
+## Installation
+
+[Complete setup instructions. Be specific about versions.]
+
+```bash
+git clone https://github.com/org/project-name.git
+cd project-name
+npm install
+cp .env.example .env  # Edit with your values
+npm run db:migrate
+```
+
+## Usage
+
+[How to use the project. Examples should be copy-pasteable.]
+
+### Basic Example
+
+```javascript
+// Show the most common use case
+```
+
+### Configuration
+
+[Environment variables, config files, CLI flags — whatever the user needs to customize.]
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABASE_URL` | PostgreSQL connection string | `postgresql://localhost:5432/mydb` |
+| `PORT` | Server port | `3000` |
+
+## Development
+
+[How to work on this project.]
+
+```bash
+npm run dev          # Start development server
+npm test             # Run tests
+npm run lint         # Check code style
+npm run build        # Build for production
+```
+
+### Project Structure
+
+[Only include if the structure is non-obvious or the project is large.]
+
+```
+src/
+  services/    # Business logic
+  routes/      # API endpoints
+  models/      # Database models
+  utils/       # Shared utilities
+tests/         # Test suites
+```
+
+## API Reference
+
+[For libraries: document the public API. For web APIs: link to full API docs.]
+
+### `functionName(param1, param2)`
+
+[Description of what it does.]
+
+**Parameters:**
+- `param1` (string) — Description
+- `param2` (object, optional) — Description
+
+**Returns:** Description of return value
+
+**Example:**
+```javascript
+const result = functionName('hello', { verbose: true });
+```
+
+## Contributing
+
+[Brief summary + link to CONTRIBUTING.md if it exists.]
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+[License type] — see [LICENSE](LICENSE) for details.
+```

package/skills/project-proposal/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: project-proposal
+description: "Write lightweight project proposals for budget approval and go/no-go decisions — problem, business case, scope, rough estimates, risks, success criteria. Triggers: project proposal, project brief, business case, budget estimate, should we build this, go/no-go, risk assessment, cost-benefit, ROI, justify this project, stakeholder approval."
+model: sonnet
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Project Proposal
+
+Write concise project proposals that help stakeholders decide whether to invest engineering resources. In agile, proposals are lightweight — enough to make an informed decision, not a 50-page waterfall spec.
+
+## When to Write a Proposal
+
+Not every task needs a proposal. Use this skill when:
+
+- **Budget approval** is needed (anything over a few days of work)
+- **Multiple stakeholders** need to agree before starting
+- **Opportunity cost** is significant (this means NOT doing something else)
+- **Risk is non-trivial** (new technology, external dependencies, data migration)
+- **The idea needs defending** — someone will ask "why should we do this?"
+
+For small features that are already in the approved roadmap, skip this and go straight to `feature-planning`.
+
+## Workflow
+
+### Step 1: Define the Problem
+
+Before proposing a solution, clearly articulate the problem:
+
+- **Who has this problem?** (Users, internal team, business)
+- **What is the impact of NOT solving it?** (Revenue loss, churn, engineering time wasted, compliance risk)
+- **How do we know this is a real problem?** (Data, user feedback, support tickets, competitive analysis)
+- **Is this urgent or important?** Urgent means it gets worse over time. Important means it has high value when solved. Both means it's a priority.
+
+If the user can't articulate the problem, help them clarify before proceeding. A solution without a clear problem is a feature request, not a project proposal.
+
+### Step 2: Propose the Solution
+
+Describe what you intend to build, at a high level:
+
+- **Approach**: What will be built and how (1-2 paragraphs, not a detailed design)
+- **Scope**: What's included and what's explicitly excluded
+- **Alternatives considered**: Why this approach over 2-3 alternatives (including "do nothing")
+- **Dependencies**: What does this project need that doesn't exist yet?
+
+### Step 3: Estimate Cost and Timeline
+
+Provide order-of-magnitude estimates (not precise):
+
+- **Team size**: How many engineers, designers, product people?
+- **Duration**: In weeks or sprints (ranges are fine: "4-6 weeks")
+- **Infrastructure cost**: New services, third-party tools, cloud resources
+- **Ongoing cost**: Maintenance, monitoring, support after launch
+
+Use the `effort-estimation` skill for detailed estimation methodology. At the proposal stage, rough ranges are appropriate.
+
+### Step 4: Assess Risks
+
+For each significant risk, document:
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [What could go wrong] | High/Med/Low | High/Med/Low | [What we'll do about it] |
+
+Common risk categories:
+- **Technical**: Unproven technology, complex integration, performance concerns
+- **Scope**: Requirements likely to change, stakeholder alignment gaps
+- **Dependencies**: External teams, third-party APIs, vendor timelines
+- **People**: Key-person dependency, skill gaps, team availability
+- **Timeline**: Hard deadlines, competing priorities, seasonal constraints
+
+### Step 5: Define Success Criteria
+
+How will you know this project succeeded? Define measurable criteria:
+
+- **Outcome metrics**: What business or user metric improves? (Conversion rate, response time, support tickets reduced)
+- **Output metrics**: What gets delivered? (Feature shipped, migration completed, performance target hit)
+- **Timeline**: When should we evaluate success? (30 days after launch, end of quarter)
+
+Link to `metrics-and-okrs` skill for deeper metric design.
+
+### Step 6: Produce the Proposal
+
+Output using the template at [templates/proposal.md](templates/proposal.md). Keep it to 1-2 pages. If it needs more, the scope is probably too large — consider splitting.
+
+## Principles Applied
+
+- **KISS**: Proposals should be 1-2 pages. If you can't explain the value concisely, the project scope is too broad.
+- **YAGNI**: Propose the minimum viable project. Nice-to-haves go in a "future considerations" section, not in the scope.
+- **Data over opinions**: Support the business case with numbers — user count, revenue impact, time savings, error rates.