Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
124 lines (93 loc) · 4.73 KB

CONTRIBUTING.md

File metadata and controls

124 lines (93 loc) · 4.73 KB

Contributing to specsmith

Bootstrap Notice

specsmith is bootstrapping its own governance process. The tool generates the Agentic AI Development Workflow for other projects, but specsmith itself is iteratively adopting that same workflow. Future versions will be developed using an older stable version of itself — the process will converge.

Until then, governance files in this repo (AGENTS.md, LEDGER.md, docs/governance/) represent the target state we are working toward, not a fully enforced process yet.

Development Setup

git clone https://github.com/BitConcepts/specsmith.git
cd specsmith
pip install -e ".[dev]"

!!! warning "Scope PYTHONPATH to this workspace only" pip install -e . creates src/specsmith.egg-info which importlib.metadata finds via PYTHONPATH=.../src. If this is set globally in your shell it leaks into every Python process — including pipx venvs — and causes version mismatches across tools.

Use the provided `.vscode/settings.json` which scopes `PYTHONPATH` to the
VS Code integrated terminal for **this workspace only**. Never export
`PYTHONPATH` in your shell profile for this purpose.

Branching Strategy (gitflow)

  • main — production-ready releases
  • develop — integration branch for next release
  • feature/* — branch from develop, merge back to develop
  • release/* — branch from develop, merge to main + develop
  • hotfix/* — branch from main, merge to main + develop
git checkout develop
git checkout -b feature/my-feature
# work, commit, push
gh pr create --base develop

Running Checks

ruff check src/ tests/ && ruff format --check src/ tests/ && mypy src/specsmith/ && pytest tests/ -v

Pre-commit

pre-commit install

Code Standards

  • SPDX headers on all .py files (MIT, BitConcepts, LLC.)
  • Must pass ruff check, ruff format --check, mypy --strict
  • All features require tests
  • Windows scripts: .cmd only (no .ps1)
  • Line length: 100

Tool Registry

When adding a new project type:

  1. Add the enum to config.py (ProjectType)
  2. Add type label and section ref to config.py (_TYPE_LABELS, _SECTION_REFS)
  3. Add directory structure to scaffolder.py (_get_empty_dirs)
  4. Add tool entries to tools.py (_TOOL_REGISTRY)
  5. Add CI metadata to tools.py (LANG_CI_META) if the language is new
  6. Add type-specific rules to templates/agents.md.j2
  7. Add type→tool-key mapping in toolrules.py (_TYPE_TOOL_KEYS)
  8. Add install commands in tool_installer.py (KNOWN_TOOLS) for any new tools
  9. Add tests for the new type

Execution Profiles

The four built-in profiles (safe, standard, open, admin) live in profiles.py. To change what commands are allowed by default in the standard profile, edit _STANDARD_ALLOWED_COMMANDS / _STANDARD_BLOCKED_COMMANDS / _STANDARD_BLOCKED_PATTERNS. New profiles can be added to the PROFILES dict — they will be available via scaffold.yml execution_profile and in the VS Code Settings panel.

Tool Rules

Curated AI context rules live in toolrules.py (TOOL_RULES dict). Each entry is a markdown bullet-list injected into the agent system prompt. When adding rules for a new tool:

  1. Add an entry to TOOL_RULES keyed by the tool executable name.
  2. Add the key to _FPGA_CHIP_TO_KEY if it's an FPGA chip name (as used in fpga_tools:).
  3. Update _TYPE_TOOL_KEYS to include it for relevant project types.

Supporting the Project

Star the repo, report issues, and consider sponsoring BitConcepts.

Importing Existing Projects

specsmith import generates governance overlay for existing projects. The detection engine in importer.py handles:

  • Language detection by file extension
  • Build system detection (pyproject.toml, Cargo.toml, CMakeLists.txt, etc.)
  • Test framework detection
  • CI and VCS platform detection
  • Module and entry point discovery

Pull Requests

  • Branch from develop (features) or main (hotfixes)
  • All CI must pass (lint, typecheck, test × 9 matrix, security)
  • Update CHANGELOG.md and docs if applicable
  • One approval required

Configurable Governance

Key tuning knobs in scaffold.yml for enterprise teams:

Setting Default Description
branching_strategy gitflow gitflow, trunk-based, github-flow
require_pr_reviews true Require reviews before merge
required_approvals 1 Number of required approvals
require_ci_pass true CI must pass before merge
allow_force_push false Allow force push to protected branches
use_remote_rules false Accept existing remote branch rules
vcs_platform github github, gitlab, bitbucket