From d92ba065a5fb75071555c1743fb5c16a4718e815 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 17:03:27 +0000 Subject: [PATCH 1/5] feat: add security guardrails to prevent credential exposure in proof artifacts Add security warnings and best practices throughout SDD workflow to prevent API keys and sensitive data from being committed in proof artifacts. Changes: - Add Security Considerations section to spec template - Add security warnings to proof artifact creation workflow - Add security validation gate to spec implementation validation - Document pre-commit hook options for secret scanning - Add security best practices section to README Related to issue #28 Co-authored-by: Damien Storm --- CONTRIBUTING.md | 40 +++++++++++++++++++++++++ README.md | 27 ++++++++++++++++- prompts/generate-spec.md | 9 ++++++ prompts/generate-task-list-from-spec.md | 2 ++ prompts/manage-tasks.md | 11 +++++++ prompts/validate-spec-implementation.md | 3 ++ 6 files changed, 91 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99ba6cc..97fed20 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,46 @@ 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 + hooks: + - id: gitleaks +``` + +**Option 2: truffleHog** +```yaml +# Add to .pre-commit-config.yaml +repos: + - repo: https://github.com/trufflesecurity/trufflehog + rev: v3.63.0 + 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 + 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. + ### Common Commands ```bash diff --git a/README.md b/README.md index d66481a..c2674ec 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. + +### 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) From 67d6c77620e88a146297010adc9d0d80cc089721 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 17:31:49 +0000 Subject: [PATCH 2/5] fix: convert bold text to proper markdown headings in CONTRIBUTING.md Fixes markdownlint errors MD036/no-emphasis-as-heading by converting bold text used as headings to proper markdown heading syntax (####). Co-authored-by: Damien Storm --- CONTRIBUTING.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97fed20..12c6dd9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,8 @@ pre-commit install 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)** +#### Option 1: gitleaks (recommended) + ```yaml # Add to .pre-commit-config.yaml repos: @@ -43,7 +44,8 @@ repos: - id: gitleaks ``` -**Option 2: truffleHog** +#### Option 2: truffleHog + ```yaml # Add to .pre-commit-config.yaml repos: @@ -54,7 +56,8 @@ repos: args: ['--trace', 'filesystem', '.'] ``` -**Option 3: detect-secrets** +#### Option 3: detect-secrets + ```yaml # Add to .pre-commit-config.yaml repos: From ccbcced913701742d01a6822314c80c8efbda3df Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Wed, 12 Nov 2025 12:36:20 -0500 Subject: [PATCH 3/5] fix: clarify developer responsibility Clarify responsibility for reviewing artifacts before pushing to remotes. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c2674ec..920753a 100644 --- a/README.md +++ b/README.md @@ -255,7 +255,7 @@ Proof artifacts are committed to your repository and may be publicly visible. ** - **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. +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 From 15bf1424c63f7451ee1270a415376da363dc80b2 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Mon, 24 Nov 2025 16:53:06 -0500 Subject: [PATCH 4/5] build(release): configure semantic release commit message Add explicit commit message template for release commits that includes [skip ci] flag to prevent CI from triggering on automated version bumps. Update configuration comments to reflect template repo nature and add reference to python-semantic-release documentation. --- .releaserc.toml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) 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 From 1edce2daa0adf809be9201aa305c2d69df997833 Mon Sep 17 00:00:00 2001 From: Damien Storm Date: Mon, 24 Nov 2025 17:02:49 -0500 Subject: [PATCH 5/5] docs: add autoupdate reminder for pre-commit hook versions --- CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12c6dd9..39c8150 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,7 +39,7 @@ To prevent accidental commits of API keys, tokens, or other sensitive data (espe # Add to .pre-commit-config.yaml repos: - repo: https://github.com/gitleaks/gitleaks - rev: v8.18.0 + rev: v8.18.0 # Update to the latest version (run `pre-commit autoupdate`) hooks: - id: gitleaks ``` @@ -50,7 +50,7 @@ repos: # Add to .pre-commit-config.yaml repos: - repo: https://github.com/trufflesecurity/trufflehog - rev: v3.63.0 + rev: v3.63.0 # Update to the latest version (run `pre-commit autoupdate`) hooks: - id: trufflehog args: ['--trace', 'filesystem', '.'] @@ -62,7 +62,7 @@ repos: # Add to .pre-commit-config.yaml repos: - repo: https://github.com/Yelp/detect-secrets - rev: v1.4.0 + rev: v1.4.0 # Update to the latest version (run `pre-commit autoupdate`) hooks: - id: detect-secrets args: ['--baseline', '.secrets.baseline'] @@ -72,6 +72,8 @@ After adding a secret scanner, run `pre-commit install` again to activate it. Th 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