diff --git a/.releaserc.toml b/.releaserc.toml index 6548fcb..6346c42 100644 --- a/.releaserc.toml +++ b/.releaserc.toml @@ -1,13 +1,17 @@ +# See https://python-semantic-release.readthedocs.io/en/latest/configuration/configuration.html +# for detailed documentation on the configuration options. + [semantic_release] # Use annotated tags like v1.2.3 tag_format = "v{version}" # Allow 0.x.x versions (required for pre-1.0.0 releases) allow_zero_version = true -# Don't update version in any files since this is a markdown-only repo -# Version is tracked via git tags only +# Don't update version in any files since this is a template repo version_variables = [] -# Generate changelog and commit version bumps +# Assets to include in the release commit assets = [] +# Commit message for release commits - includes [skip ci] to prevent CI from running +commit_message = "chore(release): {version} [skip ci]\n\nAutomatically generated by python-semantic-release" [semantic_release.changelog] # Generate CHANGELOG.md in Markdown diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99ba6cc..39c8150 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,51 @@ pre-commit install - Keep changes small and focused; prefer incremental PRs. - All prompts are plain Markdown files in the `prompts/` directory. +### Recommended: Secret Scanning Pre-commit Hooks + +To prevent accidental commits of API keys, tokens, or other sensitive data (especially in proof artifacts), consider adding secret scanning to your pre-commit configuration: + +#### Option 1: gitleaks (recommended) + +```yaml +# Add to .pre-commit-config.yaml +repos: + - repo: https://github.com/gitleaks/gitleaks + rev: v8.18.0 # Update to the latest version (run `pre-commit autoupdate`) + hooks: + - id: gitleaks +``` + +#### Option 2: truffleHog + +```yaml +# Add to .pre-commit-config.yaml +repos: + - repo: https://github.com/trufflesecurity/trufflehog + rev: v3.63.0 # Update to the latest version (run `pre-commit autoupdate`) + hooks: + - id: trufflehog + args: ['--trace', 'filesystem', '.'] +``` + +#### Option 3: detect-secrets + +```yaml +# Add to .pre-commit-config.yaml +repos: + - repo: https://github.com/Yelp/detect-secrets + rev: v1.4.0 # Update to the latest version (run `pre-commit autoupdate`) + hooks: + - id: detect-secrets + args: ['--baseline', '.secrets.baseline'] +``` + +After adding a secret scanner, run `pre-commit install` again to activate it. The scanner will automatically check files before each commit and block commits containing potential secrets. + +See the [pre-commit hooks documentation](https://pre-commit.com/hooks.html) for more secret scanning options. + +> ⚠️ **Note:** To keep your hooks current with the latest versions, periodically run `pre-commit autoupdate`. + ### Common Commands ```bash diff --git a/README.md b/README.md index d66481a..920753a 100644 --- a/README.md +++ b/README.md @@ -232,7 +232,32 @@ Once installed, you can use: - `/manage-tasks` - Manage task execution - `/validate-spec-implementation` - Validate implementation against spec -## Installation +### Option 3: MCP Server (Advanced) + +Run the prompts as an MCP server for programmatic access. This option is most useful for custom integrations and tools that support MCP. + +> Note: MCP prompt support is not uniformly supported across AI tools. See [docs/mcp-prompt-support.md](./docs/mcp-prompt-support.md) for details. + +### Workflow Essentials + +1. Open `prompts/generate-spec.md` inside your AI assistant and follow the instructions to produce a new spec in `tasks/`. +2. Point the assistant at the generated spec and run `prompts/generate-task-list-from-spec.md` to create the implementation backlog. +3. Use `prompts/manage-tasks.md` while executing work to keep status, demo criteria, and proof artifacts up to date. + +## Security Best Practices + +### Protecting Sensitive Data in Proof Artifacts + +Proof artifacts are committed to your repository and may be publicly visible. **Never commit real credentials or sensitive data.** Follow these guidelines: + +- **Replace credentials with placeholders**: Use `[YOUR_API_KEY_HERE]`, `[REDACTED]`, or `example-key-123` instead of real API keys, tokens, or passwords +- **Use example values**: When demonstrating configuration, use dummy or example data instead of production values +- **Sanitize command output**: Review CLI output and logs for accidentally captured credentials before committing +- **Consider pre-commit hooks**: Tools like [gitleaks](https://github.com/gitleaks/gitleaks), [truffleHog](https://github.com/trufflesecurity/truffleHog), or [talisman](https://github.com/thoughtworks/talisman) can automatically scan for secrets before commits + +The SDD workflow prompts include built-in reminders about security, but ultimate responsibility lies with the developer to review artifacts before committing or pushing to remotes. + +### Installation ```bash # Clone the repository diff --git a/prompts/generate-spec.md b/prompts/generate-spec.md index 43ab91d..93ce12b 100644 --- a/prompts/generate-spec.md +++ b/prompts/generate-spec.md @@ -290,6 +290,15 @@ Generate a comprehensive specification using this exact structure: [Focus on implementation constraints and HOW it will be built. Mention technical constraints, dependencies, or architectural decisions. If no technical constraints, state "No specific technical constraints identified."] +## Security Considerations + +[Identify security requirements and sensitive data handling needs. Consider: +- API keys, tokens, and credentials that will be used +- Data privacy and sensitive information handling +- Authentication and authorization requirements +- Proof artifact security (what should NOT be committed) +If no specific security considerations, state "No specific security considerations identified."] + ## Success Metrics [How will success be measured? Include specific metrics where possible.] diff --git a/prompts/generate-task-list-from-spec.md b/prompts/generate-task-list-from-spec.md index 022cb39..ff36820 100644 --- a/prompts/generate-task-list-from-spec.md +++ b/prompts/generate-task-list-from-spec.md @@ -82,6 +82,8 @@ Proof artifacts provide evidence of task completion and are essential for the up - **Enable validation** (provide evidence for `/validate-spec-implementation`) - **Support troubleshooting** (logs, error messages, configuration states) +**Security Note**: When planning proof artifacts, remember that they will be committed to the repository. Artifacts should use placeholder values for API keys, tokens, and other sensitive data rather than real credentials. + ## Chain-of-Thought Analysis Process Before generating any tasks, you must follow this reasoning process: diff --git a/prompts/manage-tasks.md b/prompts/manage-tasks.md index 044cd89..82a15e7 100644 --- a/prompts/manage-tasks.md +++ b/prompts/manage-tasks.md @@ -198,6 +198,15 @@ Each parent task must include artifacts that: - **Enable validation** (provide evidence for `/validate-spec-implementation`) - **Support troubleshooting** (logs, error messages, configuration states) +### Security Warning + +**CRITICAL**: Proof artifacts will be committed to the repository. Never include sensitive data: + +- Replace API keys, tokens, and secrets with placeholders like `[YOUR_API_KEY_HERE]` or `[REDACTED]` +- Sanitize configuration examples to remove credentials +- Use example or dummy values instead of real production data +- Review all proof artifact files before committing to ensure no sensitive information is present + ### Proof Artifact Creation Protocol ```markdown @@ -216,10 +225,12 @@ For each parent task completion: - ## Verification section showing proof artifacts demonstrate required functionality [ ] **Format with Markdown**: Use code blocks, headers, and clear organization [ ] **Verify File Content**: Ensure the markdown file contains all required evidence +[ ] **Security Check**: Scan proof file for API keys, tokens, passwords, or other sensitive data and replace with placeholders **SIMPLE VERIFICATION**: One file per task, all evidence included **CONTENT VERIFICATION**: Check the markdown file contains required sections **VERIFICATION**: Ensure proof artifact file demonstrates all required functionality +**SECURITY VERIFICATION**: Confirm no real credentials or sensitive data are present **The single markdown proof file must be created BEFORE the parent task commit** ``` diff --git a/prompts/validate-spec-implementation.md b/prompts/validate-spec-implementation.md index 5b22a33..b6bdeb0 100644 --- a/prompts/validate-spec-implementation.md +++ b/prompts/validate-spec-implementation.md @@ -74,6 +74,7 @@ If no spec is provided, follow this exact sequence: - **GATE C:** All Proof Artifacts are accessible and functional → **REQUIRED**. - **GATE D:** All changed files are either in "Relevant Files" list OR explicitly justified in git commit messages → **REQUIRED**. - **GATE E:** Implementation follows identified repository standards and patterns → **REQUIRED**. +- **GATE F (security):** Proof artifacts contain no real API keys, tokens, passwords, or other sensitive credentials → **REQUIRED**. ## Evaluation Rubric (score each 0–3 to guide severity) @@ -137,6 +138,7 @@ For each Functional Requirement, Demoable Unit, and Repository Standard: - CLI commands execute successfully with expected output - Test references exist and can be executed - Screenshots/demos show required functionality + - **Security Check**: Proof artifacts contain no real API keys, tokens, passwords, or sensitive data 3) **Requirement Coverage** - Proof Artifacts exist for each Functional Requirement @@ -163,6 +165,7 @@ For each Functional Requirement, Demoable Unit, and Repository Standard: - Any `Unknown` entries in the Coverage Matrix - Repository pattern violations (coding standards, quality gates, workflows) - Implementation that ignores identified repository conventions +- **Real API keys, tokens, passwords, or credentials in proof artifacts** (auto CRITICAL) ## Output (single human-readable Markdown report)