docs: integrate OpenSpec SDD workflow into CONTRIBUTING.md by djm81 · Pull Request #153 · nold-ai/specfact-cli

djm81 · 2026-01-27T23:06:41Z

Description

Updated CONTRIBUTING.md to integrate Spec-Driven Development (SDD) via OpenSpec, explicitly stating that all feature requests should ideally be accompanied by a spec update. This ensures clear requirements, scenarios, and implementation guidance before coding begins.

Fixes (none)

New Features (none)

Contract References: None - documentation-only change.

Type of Change

Please check all that apply:

🐛 Bug fix (non-breaking change which fixes an issue)
✨ New feature (non-breaking change which adds functionality)
💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
📚 Documentation update
🔒 Contract enforcement (adding/updating @icontract decorators)
🧪 Test enhancement (scenario tests, property-based tests)
🔧 Refactoring (code improvement without functionality change)

Contract-First Testing Evidence

Required for all changes affecting CLI commands or public APIs:

Contract Validation

Runtime contracts added/updated (@icontract decorators on public APIs)
Type checking enforced (@beartype decorators applied)
CrossHair exploration completed: hatch run contract-test-exploration
Contract violations reviewed and addressed

Test Execution

Contract validation: hatch run contract-test-contracts ✅
Contract exploration: hatch run contract-test-exploration ✅
Scenario tests: hatch run contract-test-scenarios ✅
Full test suite: hatch run contract-test-full ✅

Test Quality

CLI commands tested with typer test client
Edge cases covered with Hypothesis property tests
Error handling tested with invalid inputs
Rich console output verified manually or with snapshots

Note: This is a documentation-only change. No code changes, contracts, or tests are affected.

How Has This Been Tested?

Documentation Update: No testing required for documentation-only changes.

Manual Testing

Reviewed CONTRIBUTING.md for accuracy and completeness
Verified all OpenSpec links are correct
Confirmed SDD workflow guidance is clear
Checked that feature request guidance aligns with OpenSpec specs

Automated Testing

N/A - Documentation-only change

Test Environment

Python version: N/A
OS: N/A

Checklist

My code follows the style guidelines (PEP 8, ruff format, isort)
I have performed a self-review of my code
I have added/updated contracts (@icontract, @beartype) - N/A
I have added/updated docstrings (Google style)
I have made corresponding changes to documentation
My changes generate no new warnings (basedpyright, ruff, pylint)
All tests pass locally - N/A (documentation-only)
I have added tests that prove my fix/feature works - N/A
Any dependent changes have been merged

Quality Gates Status

Type checking ✅ (hatch run type-check) - N/A for markdown files
Linting ✅ (hatch run lint) - N/A for markdown files
Contract validation ✅ (hatch run contract-test-contracts) - N/A
Contract exploration ✅ (hatch run contract-test-exploration) - N/A
Scenario tests ✅ (hatch run contract-test-scenarios) - N/A

Changes Summary

CONTRIBUTING.md Updates

Suggesting Enhancements section:
- Added SDD guidance stating feature requests should ideally be accompanied by spec updates
- Added links to openspec/ folder and workflow instructions
- Emphasizes clear requirements and scenarios before coding
Code Contributions section:
- Added step to review OpenSpec specs before coding
- Added step to create spec proposals for new features
- Added step to update specs when implementing changes
- Updated PR creation guidance to reference OpenSpec change proposals
New "Spec-Driven Development (SDD)" section:
- Explains OpenSpec workflow and integration
- Lists when to create spec proposals vs when to skip them
- Provides comprehensive links to OpenSpec resources:
  - openspec/project.md - Project conventions
  - openspec/AGENTS.md - Workflow instructions
  - openspec/specs/ - Current specifications
  - openspec/changes/ - Proposed changes
Documentation section:
- Added requirement to update OpenSpec specs when implementing features
- Updated Documentation Structure to include openspec/ folder hierarchy

Purpose

This change integrates Spec-Driven Development (SDD) into the contribution workflow, ensuring that:

Feature requests include clear requirements and scenarios
Contributors understand the OpenSpec workflow
Specifications are maintained alongside code changes
The project follows a structured, spec-first approach

Related Work

OpenSpec folder added to repository (previous PR)
OpenSpec specs available in openspec/specs/
OpenSpec workflow documented in openspec/AGENTS.md

No version bump required - documentation-only change.

Screenshots/Recordings (if applicable)

N/A - Documentation-only change.

…command (#142) * feat: implement backlog field mapping and refinement improvements - Add FieldMapper abstract base class with canonical field names - Implement GitHubFieldMapper and AdoFieldMapper - Add custom field mapping support with YAML templates - Add field validation in refinement (story_points, business_value, priority) - Add comprehensive unit and integration tests (42 tests) - Add custom field mapping documentation - Fix custom_field_mapping parameter connection - Add early validation for custom mapping files Implements OpenSpec change: improve-backlog-field-mapping-and-refinement * perf: optimize startup performance with metadata tracking and update command - Add metadata management module for tracking version and check timestamps - Optimize startup checks to only run when needed: - Template checks: Only after version changes detected - Version checks: Limited to once per day (24h threshold) - Add --skip-checks flag for CI/CD environments - Add new 'specfact update' command for manual update checking and installation - Add comprehensive unit and integration tests (35 tests, all passing) - Update startup_checks to use metadata for conditional execution - Ensure backward compatibility (first-time users still get all checks) Performance Impact: - Startup time: Reduced from several seconds to < 1-2 seconds - Network requests: Reduced from every startup to once per day - File system operations: Reduced from every startup to only after version changes Fixes #140 Implements OpenSpec change: optimize-startup-performance * feat: request offline_access scope for Azure DevOps refresh tokens - Add offline_access scope to Azure DevOps OAuth requests - Refresh tokens now last 90 days (vs 1 hour for access tokens) - Automatic token refresh via persistent cache (no re-authentication needed) - Update documentation to reflect 90-day refresh token lifetime This addresses the issue where tokens were expiring too quickly. Refresh tokens obtained via offline_access scope enable automatic token renewal for 90 days without user interaction. Fixes token lifetime limitation issue * feat: improve CLI UX with banner control and upgrade command - Change banner to hidden by default, shown on first run or with --banner flag - Add simple version line (SpecFact CLI - vXYZ) for regular use - Rename 'update' command to 'upgrade' to avoid confusion - Update documentation for new banner behavior and upgrade command - Update startup checks message to reference 'specfact upgrade' * fix: suppress version line in test mode and fix field mapping issues - Suppress version line output in test mode and for help/version commands to prevent test failures - Fix ADO custom field mapping to honor --custom-field-mapping on writeback - Fix GitHub issue body updates to prevent duplicate sections - Ensure proper type handling for story points and business value calculations * Fix failed tests * chore: bump version to 0.26.7 and update changelog - Fixed adapter token validation tests (ADO and GitHub) - Resolved test timeout issues (commit history, AST parsing, Semgrep) - Improved test file discovery to exclude virtual environments - Added file size limits for AST parsing to prevent timeouts --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com>

* fix: add missing ADO field mappings and assignee display - Add Microsoft.VSTS.Common.AcceptanceCriteria to default field mappings - Update AdoFieldMapper to support multiple field name alternatives - Fix assignee extraction to include displayName, uniqueName, and mail - Add assignee display in preview output - Add interactive template mapping command (specfact backlog map-fields) - Update specfact init to copy backlog field mapping templates - Extend documentation with step-by-step guides Fixes #144 * test: add unit tests for ADO field mapping and assignee fixes - Add tests for Microsoft.VSTS.Common.AcceptanceCriteria field extraction - Add tests for multiple field name alternatives - Add tests for assignee extraction with displayName, uniqueName, mail - Add tests for assignee filtering with multiple identifiers - Add tests for assignee display in preview output - Add tests for interactive mapping command - Add tests for template copying in init command - Update existing tests to match new assignee extraction behavior * docs: update init command docstring to mention template copying * docs: update documentation for ADO field mapping and interactive mapping features - Update authentication guide with ADO token resolution priority - Update custom field mapping guide with interactive mapping details - Update backlog refinement guide with progress indicators and required field display - Update Azure DevOps adapter guide with field mapping improvements - Update command reference with map-fields command documentation - Update troubleshooting guide with ADO-specific issues - Update README files with new features - Update getting started guide with template initialization Co-authored-by: Cursor <cursoragent@cursor.com> * fix: address review findings for ADO field mapping - Prefer System.* fields over Microsoft.VSTS.Common.* when writing updates (fixes issue where PATCH requests could fail for Scrum templates) - Preserve existing work_item_type_mappings when saving field mappings (prevents silent erasure of custom work item type mappings) Fixes review comments: - P1: Prefer System.AcceptanceCriteria when writing updates - P2: Preserve existing work_item_type_mappings on save Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: mitigate code scanning vulnerabilities - Fix ReDoS vulnerability in github_mapper.py by replacing regex with line-by-line processing - Fix incomplete URL sanitization in github.py, bridge_sync.py, and ado.py using proper URL parsing - Add explicit permissions blocks to 7 GitHub Actions jobs following least-privilege model Resolves all 13 code scanning findings: - 1 ReDoS error - 5 URL sanitization warnings - 7 missing workflow permissions warnings Fixes #147 Co-authored-by: Cursor <cursoragent@cursor.com> * fix: accept GitHub SSH host aliases in repo detection Accept ssh.github.com (port 443) in addition to github.com when detecting GitHub repositories via SSH remotes. This ensures repositories using git@ssh.github.com:owner/repo.git are properly detected as GitHub repos. Addresses review feedback on PR #148 Co-authored-by: Cursor <cursoragent@cursor.com> * fix: prevent async cleanup issues in test mode Remove manual Live display cleanup that could cause EOFError. The _safe_progress_display function already handles test mode by skipping progress display, so direct save path is sufficient. Fixes test_unlock_section failure with EOFError/ValueError. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Dominikus Nold <djm81@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com>

Extend URL pattern matching to support ssh://git@github.com/owner/repo.git and git://github.com/owner/repo.git formats in addition to existing https?:// and scp-style git@host:path URLs. This fixes a regression where these valid GitHub URL formats were not detected, causing detect() to return false for repos using these schemes. Addresses review feedback on PR #149 Co-authored-by: Cursor <cursoragent@cursor.com>

- Update version from 0.26.8 to 0.26.9 - Add changelog entry for GitHub remote detection fix and code scanning fixes Co-authored-by: Cursor <cursoragent@cursor.com>

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>

Lowercase host_part before comparison to handle mixed-case hostnames like git@GitHub.com:org/repo.git. This restores the case-insensitive behavior from the previous config_content.lower() check and prevents regression where valid GitHub repos with mixed-case hostnames would not be detected. Addresses review feedback on PR #150 Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-01-27T23:08:28Z

SpecFact CLI Validation Report

✅ All validations passed!
Duration: 40.79s
Checks: 4 total (4 passed)

djm81 and others added 16 commits January 27, 2026 01:27

Merge branch 'main' into dev

4b167dd

Merge branch 'main' into dev

a2f6ac7

chore: bump version to 0.26.9 and update changelog

db827a0

- Update version from 0.26.8 to 0.26.9 - Add changelog entry for GitHub remote detection fix and code scanning fixes Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'main' into dev

1ade334

Signed-off-by: Dom <39115308+djm81@users.noreply.github.com>

Merge branch 'main' into dev

68cc345

Add openspec and workflow commands for transparency

dfeb7ca

Add specs from openspec

9e1f22d

Remove aisp change which wasn't implemented

115e402

Fix openspec gitignore pattern

2675361

Update gitignore

573fb7b

Update contribution standards to use openspec for SDD

907501e

djm81 self-assigned this Jan 27, 2026

djm81 added the documentation Improvements or additions to documentation label Jan 27, 2026

djm81 added this to SpecFact CLI Jan 27, 2026

github-project-automation bot moved this to Todo in SpecFact CLI Jan 27, 2026

djm81 moved this from Todo to In Progress in SpecFact CLI Jan 27, 2026

Merge branch 'main' into dev

568000c

djm81 merged commit 4bf1d01 into main Jan 27, 2026
1 of 4 checks passed

github-project-automation bot moved this from In Progress to Done in SpecFact CLI Jan 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: integrate OpenSpec SDD workflow into CONTRIBUTING.md#153

docs: integrate OpenSpec SDD workflow into CONTRIBUTING.md#153
djm81 merged 17 commits intomainfrom
dev

djm81 commented Jan 27, 2026

Uh oh!

Uh oh!

github-actions bot commented Jan 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

djm81 commented Jan 27, 2026

Description

Type of Change

Contract-First Testing Evidence

Contract Validation

Test Execution

Test Quality

How Has This Been Tested?

Manual Testing

Automated Testing

Test Environment

Checklist

Quality Gates Status

Changes Summary

CONTRIBUTING.md Updates

Purpose

Related Work

Screenshots/Recordings (if applicable)

Uh oh!

Uh oh!

github-actions bot commented Jan 27, 2026

SpecFact CLI Validation Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant