docs(skill): generalise SKILL.md for any programming language
Remove project-specific src/cleveragents/ path (now src/<package>/ with examples). Replace all bare nox/Pyright/ruff/Behave references with the language-agnostic 'task runner / type checker / linter / BDD framework' abstractions, keeping the project-specific tool as a parenthetical example. Add ecosystem-equivalents reference table (Python, JS/TS, Java/Kotlin, Go) in the Quick Command Reference. Generalise type-suppression rules across languages (# type: ignore, @ts-ignore, @SuppressWarnings). Generalise TDD assertion failure type requirement with Python, Java, and JS examples. Generalise import rules, project manifest references, and directory layout descriptions. Remove Python-only step-file naming; add multi-language examples throughout. LangChain/LangGraph and v3/legacy plan workflow sections are left as-is and clearly labelled as project-specific. ISSUES CLOSED: #0
This commit is contained in:
@@ -16,22 +16,28 @@ description: |
|
||||
contributing to CleverThis.
|
||||
|
||||
Covers: commit format and quality rules, pull request requirements and merge
|
||||
criteria, BDD testing with Behave (unit) and Robot Framework (integration),
|
||||
coverage threshold (97% project-specific), Pyright type checking, nox task
|
||||
runner commands (all sessions), CI/CD pipeline (all jobs + required gates),
|
||||
issue hierarchy (Issue→Epic→Legendary), label system (State/Priority/MoSCoW/
|
||||
Type/), ticket lifecycle, sprint structure (2-week, 1st and 15th), DSDM
|
||||
triaging, MoSCoW prioritization, point estimation (poker points), branch
|
||||
naming conventions (feature/mN-, bugfix/mN-, tdd/mN-), TDD bug fix workflow
|
||||
with exact tag validation rules (AssertionError requirement), file organization
|
||||
(src/ features/ robot/ docs/ config/ scripts/ examples/ k8s/), documentation
|
||||
traceability rules (no line numbers, module.class.method + commit hash),
|
||||
code style principles, SOLID patterns, error handling rules, security policies
|
||||
(gopass, Yubikey, encryption), confidentiality levels (Restricted/Secret/Trade
|
||||
Secret/Confidential/Public), organizational structure, boards (ELB/OCRB),
|
||||
committees (12 committees), FOSS policies, open standards mandate, backwards
|
||||
compatibility policy (none pre-v3.0.0), v3 vs legacy plan workflow,
|
||||
LangChain/LangGraph guidelines, and definition of done.
|
||||
criteria, BDD testing (project uses Behave for unit and Robot Framework for
|
||||
integration), coverage threshold (97% project-specific), static type checking
|
||||
(project uses Pyright), task runner commands (project uses nox), CI/CD pipeline
|
||||
(all jobs + required gates), issue hierarchy (Issue→Epic→Legendary), label
|
||||
system (State/Priority/MoSCoW/Type/), ticket lifecycle, sprint structure
|
||||
(2-week, 1st and 15th), DSDM triaging, MoSCoW prioritization, point estimation
|
||||
(poker points), branch naming conventions (feature/mN-, bugfix/mN-, tdd/mN-),
|
||||
TDD bug fix workflow with exact tag validation rules (assertion failure type
|
||||
requirement), file organization (src/ test/ docs/ config/ scripts/ examples/),
|
||||
documentation traceability rules (no line numbers, logical module path +
|
||||
commit hash), code style principles, SOLID patterns, error handling rules,
|
||||
security policies (gopass, Yubikey, encryption), confidentiality levels
|
||||
(Restricted/Secret/Trade Secret/Confidential/Public), organizational structure,
|
||||
boards (ELB/OCRB), committees (12 committees), FOSS policies, open standards
|
||||
mandate, backwards compatibility policy, project-specific CLI workflow
|
||||
(v3 vs legacy), AI framework guidelines (LangChain/LangGraph), and
|
||||
definition of done.
|
||||
|
||||
All tooling references are framed as project-specific examples. The rules
|
||||
themselves apply universally; specific tools (nox, Pyright, ruff, Behave,
|
||||
Robot Framework) are the current project's choices for a Python codebase, with
|
||||
equivalents for other language ecosystems noted throughout.
|
||||
references:
|
||||
- commits
|
||||
- pull-requests
|
||||
@@ -59,39 +65,58 @@ and the project-specific **CONTRIBUTING.md**.
|
||||
|
||||
## ⚡ Quick Command Reference
|
||||
|
||||
> **Language / tooling note:** The commands below are the **project-specific** examples
|
||||
> using Python and nox. The underlying principle applies to any language: **always use
|
||||
> the project's designated task runner** — never invoke linters, type checkers, or test
|
||||
> frameworks directly. Common equivalents by ecosystem:
|
||||
>
|
||||
> | Concern | Python *(this project)* | JavaScript / TypeScript | Java / Kotlin | Go |
|
||||
> |---------|------------------------|------------------------|---------------|----|
|
||||
> | Task runner | `nox` | `npm run` / `pnpm run` | Gradle / Maven | `make` / `mage` |
|
||||
> | Linter | ruff | ESLint / Biome | Checkstyle / Detekt | golangci-lint |
|
||||
> | Formatter | ruff format | Prettier | google-java-format | gofmt |
|
||||
> | Type checker | Pyright | tsc (strict) | javac / kotlinc | built-in |
|
||||
> | Unit tests (BDD) | Behave | jest-cucumber / vitest | Cucumber-JVM | godog |
|
||||
> | Integration tests | Robot Framework | Playwright / Cypress | Selenium | `go test` (tagged) |
|
||||
> | Coverage | Slipcover | Istanbul / c8 | JaCoCo | `go test -cover` |
|
||||
> | Security scan | bandit + semgrep | npm audit + semgrep | SpotBugs | gosec |
|
||||
> | Benchmarks | ASV | Benchmark.js | JMH | `go test -bench` |
|
||||
> | Build / package | hatch build | npm pack / vite build | `./gradlew build` | `go build` |
|
||||
> | Docs | MkDocs | VitePress / Docusaurus | Javadoc | pkg.go.dev |
|
||||
|
||||
```bash
|
||||
# Run ALL quality gates (must pass before any PR)
|
||||
# Run ALL quality gates (must pass before any PR) — Python/nox:
|
||||
nox
|
||||
|
||||
# Core quality sessions:
|
||||
nox -s lint # ruff linting + format check
|
||||
nox -s format # auto-format code with ruff
|
||||
nox -s format -- --check # check formatting only (no changes) — used in CI
|
||||
nox -s typecheck # Pyright type checking (strict, no suppressions)
|
||||
nox -s security_scan # bandit + semgrep + vulture
|
||||
nox -s dead_code # vulture dead code detection
|
||||
nox -s lint # linting + format check (ruff)
|
||||
nox -s format # auto-format code (ruff)
|
||||
nox -s format -- --check # check formatting only, no changes — CI mode
|
||||
nox -s typecheck # static type checking (Pyright, strict, no suppressions)
|
||||
nox -s security_scan # security scan (bandit + semgrep + vulture)
|
||||
nox -s dead_code # dead code detection (vulture)
|
||||
|
||||
# Test sessions:
|
||||
nox -s unit_tests # Behave BDD unit tests (features/)
|
||||
nox -s integration_tests # Robot Framework via pabot (robot/)
|
||||
nox -s e2e_tests # End-to-end Robot tests with real LLM keys
|
||||
nox -s coverage_report # Slipcover coverage report (must be ≥ 97%)
|
||||
nox -s benchmark # Airspeed Velocity (ASV) performance benchmarks
|
||||
nox -s benchmark_regression # ASV benchmark regression check (PRs only)
|
||||
nox -s unit_tests # BDD unit tests (Behave — features/)
|
||||
nox -s integration_tests # integration tests (Robot Framework via pabot — robot/)
|
||||
nox -s e2e_tests # end-to-end tests with real external credentials
|
||||
nox -s coverage_report # coverage report (Slipcover — must be ≥ 97%)
|
||||
nox -s benchmark # performance benchmarks (Airspeed Velocity)
|
||||
nox -s benchmark_regression # benchmark regression check (PRs only)
|
||||
|
||||
# Analysis sessions:
|
||||
nox -s complexity # Radon complexity analysis (nightly quality sweep)
|
||||
nox -s complexity # code complexity (Radon — nightly quality sweep)
|
||||
|
||||
# Build/docs sessions:
|
||||
nox -s docs # build documentation with MkDocs
|
||||
nox -s build # build wheel distribution
|
||||
# Build / docs sessions:
|
||||
nox -s docs # build documentation (MkDocs)
|
||||
nox -s build # build distributable (wheel)
|
||||
|
||||
# Setup dev environment (installs pre-commit hooks):
|
||||
scripts/setup-dev.sh
|
||||
# Dev environment setup:
|
||||
scripts/setup-dev.sh # installs pre-commit hooks
|
||||
|
||||
# Install Commitizen (interactive commit messages):
|
||||
# Conventional commit message helper (works for any language project):
|
||||
npm install -g commitizen@2.8.6 cz-customizable@4.0.0
|
||||
git cz # use instead of git commit
|
||||
git cz # interactive commit — replaces git commit
|
||||
|
||||
# Release (triggers CI release.yml workflow):
|
||||
git tag v3.6.0 && git push origin v3.6.0
|
||||
@@ -109,7 +134,7 @@ What are you about to do?
|
||||
├─ Write or commit code
|
||||
│ ├─ Before writing → "Am I about to write code?" tree below
|
||||
│ ├─ Before committing → "Am I about to commit?" tree below
|
||||
│ └─ About to push → run nox first, verify all gates pass
|
||||
│ └─ About to push → run the task runner first (e.g. nox), verify all gates pass
|
||||
│
|
||||
├─ Create or update an issue/ticket
|
||||
│ ├─ New issue → "Am I creating an issue?" tree below
|
||||
@@ -213,23 +238,33 @@ Before writing any code:
|
||||
│
|
||||
├─ Code style checklist (before writing):
|
||||
│ ├─ Write tests BEFORE implementation (test-first, no exceptions)
|
||||
│ ├─ Is this Python? → use full type annotations everywhere
|
||||
│ ├─ Will code be in src/ only? (no mocks/test-data in production src/)
|
||||
│ ├─ Use the language's type system fully — no inline suppression of type errors:
|
||||
│ │ ├─ Python → full type annotations on all functions, variables, and returns
|
||||
│ │ ├─ TypeScript → strict mode enabled; avoid `any`
|
||||
│ │ ├─ Java / C# / Kotlin → rely on compiler types; use generics appropriately
|
||||
│ │ └─ No type-suppression comments regardless of language
|
||||
│ │ (Python: # type: ignore | TS: // @ts-ignore | Java: @SuppressWarnings)
|
||||
│ ├─ Production source only in src/ — no mocks or test data there
|
||||
│ ├─ Are you using SOLID principles? (see references/code-style/)
|
||||
│ └─ File under 500 lines? (break into modules if approaching limit)
|
||||
│
|
||||
├─ Is this LangChain/LangGraph code?
|
||||
├─ Is this LangChain/LangGraph code? (project-specific — this project uses Python LangGraph)
|
||||
│ ├─ Use TypedDict for state, verb-based node names
|
||||
│ ├─ Use BaseLanguageModel / BaseLLM unified interfaces
|
||||
│ ├─ Always use MemorySaver for checkpointing
|
||||
│ ├─ Use ChatPromptTemplate or PromptTemplate for prompts
|
||||
│ └─ See references/code-style/README.md (LangChain/LangGraph section)
|
||||
│
|
||||
└─ Import rules:
|
||||
├─ All imports at top of file, never inside functions/methods
|
||||
├─ Never inside if/try/for blocks
|
||||
├─ Exception: TYPE_CHECKING only for circular-dependency avoidance
|
||||
└─ Prefer specific symbols: from module import ClassName
|
||||
└─ Dependency / import declaration rules:
|
||||
├─ Declare all imports/dependencies at the top of the file (language-idiomatic)
|
||||
├─ Never scatter them throughout code or bury them inside functions or blocks
|
||||
├─ Prefer specific imports over wildcard or whole-module imports:
|
||||
│ ├─ Python: from module import ClassName (not import *)
|
||||
│ ├─ Java: explicit class imports (not import java.util.*)
|
||||
│ └─ TypeScript: import { Foo } from './foo' (named imports)
|
||||
└─ Exception: type-only imports for circular-dependency avoidance
|
||||
├─ Python: if TYPE_CHECKING: block
|
||||
└─ TypeScript: import type { Foo } from './foo'
|
||||
```
|
||||
|
||||
### "Am I about to commit?"
|
||||
@@ -240,11 +275,11 @@ Before every commit:
|
||||
├─ Have all tests been written for this change?
|
||||
│ └─ NO → Write tests first (test-first development)
|
||||
│
|
||||
├─ Run quality gates:
|
||||
│ ├─ nox -s lint → must be green
|
||||
│ ├─ nox -s typecheck → must be green (Pyright, no suppressions)
|
||||
│ ├─ nox -s unit_tests → must be green
|
||||
│ └─ nox -s coverage_report → must be ≥ 97%
|
||||
├─ Run quality gates (use the task runner — see "What task runner session should I run?"):
|
||||
│ ├─ Lint session → must be green (e.g. nox -s lint)
|
||||
│ ├─ Type check session → must be green, no inline suppressions (e.g. nox -s typecheck)
|
||||
│ ├─ Unit test session → must be green (e.g. nox -s unit_tests)
|
||||
│ └─ Coverage session → must be ≥ 97% (e.g. nox -s coverage_report)
|
||||
│
|
||||
├─ Self-review the diff:
|
||||
│ ├─ Only intended changes staged? (use git add -p)
|
||||
@@ -282,9 +317,10 @@ Before every commit:
|
||||
PR submission checklist (ALL must be true):
|
||||
│
|
||||
├─ CODE QUALITY
|
||||
│ ├─ nox (full suite) passes with zero failures
|
||||
│ ├─ Coverage ≥ 97% (nox -s coverage_report)
|
||||
│ ├─ No type: ignore suppressions anywhere
|
||||
│ ├─ Task runner full suite passes with zero failures (e.g. nox)
|
||||
│ ├─ Coverage ≥ 97% (e.g. nox -s coverage_report)
|
||||
│ ├─ No inline type-checking suppressions anywhere
|
||||
│ │ (Python: # type: ignore | TypeScript: // @ts-ignore | Java: @SuppressWarnings)
|
||||
│ └─ All pre-commit hooks pass
|
||||
│
|
||||
├─ COMMIT STRUCTURE
|
||||
@@ -351,7 +387,7 @@ Code review responsibilities:
|
||||
│ ├─ Readability: clear names, easy to follow, no magic numbers?
|
||||
│ ├─ Performance: no unnecessary inefficiencies or N+1 problems?
|
||||
│ ├─ Security: no vulnerabilities, secrets, or unsafe patterns?
|
||||
│ ├─ Style: follows project coding standards (ruff, Pyright)?
|
||||
│ ├─ Style: follows project coding standards (linter, type checker)?
|
||||
│ ├─ Tests: adequate coverage? edge cases covered? error paths tested?
|
||||
│ ├─ Coverage: does coverage remain ≥ 97%?
|
||||
│ └─ Documentation: updated alongside code changes?
|
||||
@@ -541,19 +577,20 @@ Work is DONE only when ALL of the following are true:
|
||||
│ └─ All subtasks in the issue checklist are checked off
|
||||
│
|
||||
├─ TESTS (MANDATORY)
|
||||
│ ├─ BDD Behave scenarios written BEFORE implementation (test-first)
|
||||
│ ├─ BDD scenarios written BEFORE implementation (project uses Behave;
|
||||
│ │ other frameworks: Cucumber, SpecFlow, pytest-bdd, rspec, godog)
|
||||
│ ├─ Unit tests cover all non-trivial logic paths
|
||||
│ ├─ Integration tests updated/added if component interfaces changed
|
||||
│ ├─ nox -s unit_tests → green
|
||||
│ ├─ nox -s integration_tests → green
|
||||
│ └─ nox -s coverage_report → ≥ 97% (project-specific threshold)
|
||||
│ ├─ Task runner unit test session → green (e.g. nox -s unit_tests)
|
||||
│ ├─ Task runner integration test session → green (e.g. nox -s integration_tests)
|
||||
│ └─ Task runner coverage session → ≥ 97% (e.g. nox -s coverage_report)
|
||||
│
|
||||
├─ CODE QUALITY
|
||||
│ ├─ nox -s lint → green (ruff, no suppressions)
|
||||
│ ├─ nox -s typecheck → green (Pyright, no type: ignore)
|
||||
│ ├─ nox -s security_scan → green
|
||||
│ ├─ nox -s dead_code → no new dead code introduced
|
||||
│ └─ nox (full default suite) → all green
|
||||
│ ├─ Task runner lint session → green, no suppressions (e.g. nox -s lint)
|
||||
│ ├─ Task runner type check session → green, no inline suppressions (e.g. nox -s typecheck)
|
||||
│ ├─ Task runner security scan session → green (e.g. nox -s security_scan)
|
||||
│ ├─ Task runner dead code session → no new dead code (e.g. nox -s dead_code)
|
||||
│ └─ Task runner full default suite → all green (e.g. nox)
|
||||
│
|
||||
├─ COMMIT AND PR
|
||||
│ ├─ Atomic commit with correct Conventional Changelog format
|
||||
@@ -568,7 +605,8 @@ Work is DONE only when ALL of the following are true:
|
||||
│
|
||||
├─ DOCUMENTATION
|
||||
│ ├─ Documentation updated alongside code in same commit
|
||||
│ ├─ References use module.class.method (never line numbers)
|
||||
│ ├─ References use logical module path — never line numbers
|
||||
│ │ └─ Python example: mypackage.services.plan_service.PlanService.execute
|
||||
│ ├─ Changelog has one new entry for this commit
|
||||
│ └─ CONTRIBUTORS.md updated if first contribution
|
||||
│
|
||||
@@ -723,37 +761,40 @@ Testing requirements (MANDATORY at all levels):
|
||||
│ ├─ Tests go in same commit as the implementation they test
|
||||
│ └─ Never commit implementation without its tests
|
||||
│
|
||||
├─ UNIT TESTS (Behave / BDD / Gherkin)
|
||||
│ ├─ Framework: Behave (Cucumber/Gherkin standard)
|
||||
│ ├─ Location: features/ directory ONLY
|
||||
│ ├─ Mocks/fakes location: features/mocks/ subdirectory
|
||||
│ ├─ DO NOT write xUnit-style tests (pytest assertions alone, JUnit, etc.)
|
||||
│ ├─ All unit-level tests = Gherkin feature files + step definitions
|
||||
├─ UNIT TESTS — BDD / Gherkin (project uses Behave)
|
||||
│ ├─ All unit-level tests must follow Behavior-Driven Development (BDD)
|
||||
│ ├─ Framework: project uses Behave; other options: Cucumber, SpecFlow, pytest-bdd, rspec, godog
|
||||
│ ├─ Test format: human-readable Gherkin feature files + step definitions
|
||||
│ ├─ Location: designated unit test directory (project: features/)
|
||||
│ ├─ Mock/fake location: mock subdirectory within test dir (project: features/mocks/)
|
||||
│ ├─ DO NOT write xUnit-style tests (raw assertions without BDD structure)
|
||||
│ ├─ Step files: group by feature, add to existing files before creating new
|
||||
│ ├─ Steps for foo.feature → foo_steps.py; shared steps → reusable named file
|
||||
│ ├─ Never commit placeholder steps (all steps must be implemented)
|
||||
│ ├─ Mocks/fakes/stubs: allowed in unit tests, location: features/mocks/ ONLY
|
||||
│ ├─ Run via: nox -s unit_tests
|
||||
│ └─ Coverage threshold: ≥ 97% (measured by nox -s coverage_report)
|
||||
│ ├─ Name step files after their feature (Python example: foo_steps.py for foo.feature)
|
||||
│ ├─ Never commit placeholder steps (all steps must be fully implemented)
|
||||
│ ├─ Mocks/fakes/stubs: allowed ONLY in unit tests, in the designated mock location
|
||||
│ ├─ Run via: task runner unit test session (e.g. nox -s unit_tests)
|
||||
│ └─ Coverage threshold: ≥ 97% (e.g. nox -s coverage_report)
|
||||
│
|
||||
├─ INTEGRATION TESTS (Robot Framework)
|
||||
│ ├─ Framework: Robot Framework via pabot (parallel)
|
||||
│ ├─ Location: robot/ directory
|
||||
│ ├─ Run via: nox -s integration_tests
|
||||
├─ INTEGRATION TESTS (project uses Robot Framework)
|
||||
│ ├─ Framework: keyword-driven integration tests (project: Robot Framework via pabot)
|
||||
│ ├─ Other frameworks: Playwright, Cypress, Selenium, `go test` (integration tag)
|
||||
│ ├─ Location: integration test directory (project: robot/)
|
||||
│ ├─ Run via: task runner integration test session (e.g. nox -s integration_tests)
|
||||
│ ├─ Exercise real services, endpoints, dependencies
|
||||
│ ├─ NO mocking in integration tests (strictly prohibited)
|
||||
│ ├─ Mocks OK for truly impractical external dependencies only
|
||||
│ ├─ Mocks acceptable ONLY for truly impractical external dependencies
|
||||
│ └─ Must be updated when component interfaces change
|
||||
│
|
||||
├─ END-TO-END TESTS (Robot Framework with real LLM keys)
|
||||
│ ├─ Run via: nox -s e2e_tests
|
||||
│ ├─ Requires real LLM API keys (separate from integration tests)
|
||||
│ └─ Tests the full system with real providers
|
||||
├─ END-TO-END TESTS (project uses Robot Framework with real credentials)
|
||||
│ ├─ Run via: task runner e2e session (e.g. nox -s e2e_tests)
|
||||
│ ├─ Requires real external service credentials (separate from integration tests)
|
||||
│ └─ Tests the complete system with real providers end-to-end
|
||||
│
|
||||
├─ PERFORMANCE BENCHMARKS
|
||||
│ ├─ Use ASV (Airspeed Velocity) for performance-sensitive code
|
||||
│ ├─ Run via: nox -s benchmark
|
||||
│ └─ PRs: regression check via nox -s benchmark_regression
|
||||
│ ├─ Write benchmarks for performance-sensitive code
|
||||
│ │ (project: ASV — Airspeed Velocity; others: JMH, Benchmark.js, `go test -bench`)
|
||||
│ ├─ Run via: task runner benchmark session (e.g. nox -s benchmark)
|
||||
│ └─ PRs: regression check via task runner (e.g. nox -s benchmark_regression)
|
||||
│
|
||||
├─ COVERAGE REQUIREMENTS
|
||||
│ ├─ Minimum: ≥ 97% (project-specific; C.O.C. baseline is 85%)
|
||||
@@ -769,25 +810,29 @@ Testing requirements (MANDATORY at all levels):
|
||||
│ └─ Regression tests for every bug fix (via TDD workflow)
|
||||
│
|
||||
├─ MOCK PLACEMENT (strict)
|
||||
│ ├─ Mocks/fakes/stubs/fixtures: features/mocks/ directory ONLY
|
||||
│ ├─ NEVER in src/, NEVER in scripts/
|
||||
│ ├─ Production code must not contain if testing: guards or test-only paths
|
||||
│ ├─ Mocks/fakes/stubs/fixtures: designated mock directory ONLY (project: features/mocks/)
|
||||
│ ├─ NEVER in production source directory (src/) or scripts/
|
||||
│ ├─ Production code must not contain if-testing guards or test-only code paths
|
||||
│ └─ Use dependency injection to substitute test doubles
|
||||
│
|
||||
├─ TDD BUG FIX TAGS (see also "Am I writing a TDD issue-capture test?")
|
||||
│ ├─ Required tags: @tdd_issue + @tdd_issue_N + @tdd_expected_fail
|
||||
│ ├─ @tdd_expected_fail inverts result: failing assertion = CI passes
|
||||
│ └─ AssertionError ONLY: use assert or raise AssertionError (not ValueError etc.)
|
||||
│ └─ Must use the language's assertion failure type — NOT runtime exceptions
|
||||
│ (Python: AssertionError | Java: AssertionError | JS: assert.AssertionError)
|
||||
│
|
||||
├─ LangChain/LangGraph testing specifics
|
||||
├─ LangChain/LangGraph testing (project-specific — Python LangGraph)
|
||||
│ ├─ Use FakeListLLM or custom mock providers (deterministic)
|
||||
│ ├─ Test each node's state transformation independently
|
||||
│ ├─ Verify complete workflow with expected state transitions
|
||||
│ └─ Test both event emission and final results for streaming
|
||||
│
|
||||
└─ RUNNING TESTS
|
||||
├─ Always use nox (never invoke frameworks directly from command line)
|
||||
├─ If nox session is missing → add it to nox configuration first
|
||||
├─ Always use the task runner — never invoke frameworks directly
|
||||
│ Python/nox: never call `behave`, `robot`, or `pytest` directly — use `nox`
|
||||
│ Node.js: never call `jest` directly — use `npm run test`
|
||||
│ Java: never call `junit` directly — use `./gradlew test`
|
||||
├─ If a task runner session is missing → add it to the task runner config FIRST
|
||||
└─ Test failure during development → immediately becomes blocking task
|
||||
```
|
||||
|
||||
@@ -837,7 +882,7 @@ Conventional Changelog commit message format:
|
||||
│ └─ Use EXACTLY the text from ## Metadata section (copy-paste, verbatim)
|
||||
│
|
||||
└─ TOOLS
|
||||
├─ Commitizen: git cz (interactive, recommended)
|
||||
├─ Commitizen: git cz (interactive, recommended — works for any language project)
|
||||
├─ npm install -g commitizen@2.8.6 cz-customizable@4.0.0
|
||||
└─ Pre-commit hook validates format automatically
|
||||
```
|
||||
@@ -856,14 +901,16 @@ Mandatory Bug Fix TDD Workflow:
|
||||
├─ STEP 2: Write the failing test
|
||||
│ ├─ Branch naming: tdd/mN-<name> (N = milestone number)
|
||||
│ │ e.g.: tdd/m3-shacl-crash
|
||||
│ ├─ Write Behave scenario that captures the buggy behavior
|
||||
│ ├─ Write a BDD scenario that captures the buggy behavior (project uses Behave)
|
||||
│ ├─ Tag the test with ALL THREE tags (see Tag Validation Rules below):
|
||||
│ │ ├─ @tdd_issue
|
||||
│ │ ├─ @tdd_issue_N (N = bug issue number, e.g. @tdd_issue_123)
|
||||
│ │ └─ @tdd_expected_fail ← CRITICAL: inverts pass/fail in CI
|
||||
│ ├─ The test MUST fail when run normally (it proves the bug exists)
|
||||
│ └─ ⚠️ AssertionError ONLY: use assert or raise AssertionError
|
||||
│ Do NOT use ValueError, RuntimeError, OSError — those are NOT inverted
|
||||
│ └─ ⚠️ Use the language's assertion failure type ONLY — NOT runtime exceptions:
|
||||
│ Python: use `assert` or `raise AssertionError(...)` — not ValueError/RuntimeError
|
||||
│ Java: throw new AssertionError(...) — not RuntimeException
|
||||
│ JavaScript: throw new assert.AssertionError(...) — not Error or TypeError
|
||||
│
|
||||
├─ STEP 3: Merge the TDD test PR
|
||||
│ ├─ CI passes because @tdd_expected_fail inverts the result
|
||||
@@ -894,7 +941,7 @@ Mandatory Bug Fix TDD Workflow:
|
||||
├─ TAG VALIDATION RULES (enforced by CI)
|
||||
│ ├─ @tdd_issue_N present → @tdd_issue MUST also be present
|
||||
│ ├─ @tdd_expected_fail present → @tdd_issue AND @tdd_issue_N MUST be present
|
||||
│ ├─ Expected-fail steps MUST fail via AssertionError (not other exceptions)
|
||||
│ ├─ Expected-fail steps MUST fail via the language's assertion type (not runtime exceptions)
|
||||
│ ├─ Bug fix PR closing #N → @tdd_expected_fail MUST be removed from @tdd_issue_N
|
||||
│ └─ Bug fix PR closing #N → @tdd_issue_N test MUST exist in codebase
|
||||
│
|
||||
@@ -1192,12 +1239,13 @@ Documentation standards (all code-related docs):
|
||||
│ └─ Updated doc: find the single canonical location and update there
|
||||
│
|
||||
├─ TRACEABILITY RULES (enforced)
|
||||
│ ├─ Reference code by LOGICAL LOCATION only:
|
||||
│ │ └─ Format: module.class.method
|
||||
│ │ e.g. cleveragents.services.plan_service.PlanService.execute
|
||||
│ ├─ Reference code by LOGICAL LOCATION only (language-appropriate format):
|
||||
│ │ ├─ Python example: mypackage.services.plan_service.PlanService.execute
|
||||
│ │ ├─ Java example: com.example.services.PlanService.execute
|
||||
│ │ └─ TypeScript: services/planService.PlanService.execute
|
||||
│ ├─ Include commit hash at time of writing
|
||||
│ │ └─ e.g. (see commit a3f92b1)
|
||||
│ ├─ ⚠️ NEVER reference by line number (file.py:142)
|
||||
│ ├─ ⚠️ NEVER reference by line number (e.g. file.py:142 or file.go:87)
|
||||
│ │ Line numbers shift with every edit and become misleading immediately
|
||||
│ └─ When names are refactored later, commit hash traces original location
|
||||
│
|
||||
@@ -1219,15 +1267,15 @@ Documentation standards (all code-related docs):
|
||||
│ ├─ When code ≠ spec → code is wrong, align code to spec
|
||||
│ └─ Spec changes: go through ADR process, not ad-hoc edits
|
||||
│
|
||||
├─ CODE DOCUMENTATION (doc strings, comments)
|
||||
│ ├─ All public functions, classes, methods → docstrings required
|
||||
├─ CODE DOCUMENTATION (docstrings / doc comments)
|
||||
│ ├─ All public functions, classes, methods → docstrings/doc comments required
|
||||
│ ├─ Non-obvious logic → inline comments explaining WHY (not what)
|
||||
│ ├─ Avoid comments that merely restate the code
|
||||
│ └─ Keep comments current when code changes
|
||||
│
|
||||
├─ DOCS DIRECTORY (docs/)
|
||||
│ ├─ All markdown files must be written for MkDocs format
|
||||
│ ├─ Build with: nox -s docs
|
||||
│ ├─ All markdown files must be written for the project's doc tool (project: MkDocs)
|
||||
│ ├─ Build with: task runner docs session (e.g. nox -s docs)
|
||||
│ └─ API docs, architecture overviews, user guides → all in docs/
|
||||
│
|
||||
└─ CHANGELOG
|
||||
@@ -1235,47 +1283,47 @@ Documentation standards (all code-related docs):
|
||||
└─ Describes the change from the user's perspective
|
||||
```
|
||||
|
||||
### "What nox session should I run?"
|
||||
### "What task runner session should I run?"
|
||||
|
||||
```
|
||||
Complete nox session guide:
|
||||
Complete task runner guide (this project uses nox — Python):
|
||||
│
|
||||
├─ BEFORE COMMITTING (run all of these):
|
||||
│ ├─ nox -s lint → ruff linting (find code style violations)
|
||||
│ ├─ nox -s format -- --check → check if formatting passes (CI mode)
|
||||
│ ├─ nox -s typecheck → Pyright static type checking
|
||||
│ ├─ nox -s unit_tests → Behave BDD tests
|
||||
│ └─ nox -s coverage_report → verify ≥ 97% coverage
|
||||
│ ├─ Lint session → linting (nox -s lint)
|
||||
│ ├─ Format check session → formatting only, no changes (nox -s format -- --check)
|
||||
│ ├─ Type check session → static type checking (nox -s typecheck)
|
||||
│ ├─ Unit test session → BDD tests (nox -s unit_tests)
|
||||
│ └─ Coverage session → verify ≥ 97% (nox -s coverage_report)
|
||||
│
|
||||
├─ BEFORE SUBMITTING A PR (additionally run):
|
||||
│ ├─ nox → ALL default sessions (the full gate)
|
||||
│ ├─ nox -s security_scan → bandit + semgrep + vulture
|
||||
│ ├─ nox -s dead_code → vulture dead code detection
|
||||
│ └─ nox -s integration_tests → Robot Framework integration tests
|
||||
│ ├─ Full default suite → ALL sessions (nox)
|
||||
│ ├─ Security scan session → bandit + semgrep + vulture (nox -s security_scan)
|
||||
│ ├─ Dead code session → vulture (nox -s dead_code)
|
||||
│ └─ Integration test session → Robot Framework (nox -s integration_tests)
|
||||
│
|
||||
├─ SPECIFIC SITUATIONS:
|
||||
│ ├─ Auto-fix formatting: nox -s format
|
||||
│ ├─ Run e2e tests: nox -s e2e_tests (needs real LLM keys)
|
||||
│ ├─ Performance benchmarks: nox -s benchmark
|
||||
│ ├─ Benchmark regression: nox -s benchmark_regression
|
||||
│ ├─ Code complexity: nox -s complexity (radon; nightly sweep)
|
||||
│ ├─ Build docs: nox -s docs
|
||||
│ ├─ Build wheel: nox -s build
|
||||
│ └─ Build everything: nox
|
||||
│ ├─ Auto-fix formatting: Format session (nox -s format)
|
||||
│ ├─ End-to-end tests: E2E session — needs real credentials (nox -s e2e_tests)
|
||||
│ ├─ Performance benchmarks: Benchmark session (nox -s benchmark)
|
||||
│ ├─ Benchmark regression: Benchmark regression session (nox -s benchmark_regression)
|
||||
│ ├─ Code complexity analysis: Complexity session — Radon (nox -s complexity)
|
||||
│ ├─ Build documentation: Docs session — MkDocs (nox -s docs)
|
||||
│ ├─ Build distributable: Build session (nox -s build)
|
||||
│ └─ Run everything: Full default suite (nox)
|
||||
│
|
||||
├─ CI JOBS AND THEIR SESSIONS:
|
||||
│ ├─ lint job → nox -s lint + nox -s format -- --check
|
||||
│ ├─ typecheck job → nox -s typecheck
|
||||
│ ├─ security job → nox -s security_scan + nox -s dead_code
|
||||
│ ├─ quality job → nox -s complexity
|
||||
│ ├─ unit_tests job → nox -s unit_tests
|
||||
├─ CI JOBS AND THEIR SESSIONS (project-specific mapping):
|
||||
│ ├─ lint job → nox -s lint + nox -s format -- --check
|
||||
│ ├─ typecheck job → nox -s typecheck
|
||||
│ ├─ security job → nox -s security_scan + nox -s dead_code
|
||||
│ ├─ quality job → nox -s complexity
|
||||
│ ├─ unit_tests job → nox -s unit_tests
|
||||
│ ├─ integration_tests job → nox -s integration_tests
|
||||
│ ├─ e2e_tests job → nox -s e2e_tests
|
||||
│ ├─ coverage job → nox -s coverage_report (fail-under 97%)
|
||||
│ ├─ benchmark-regression → nox -s benchmark_regression
|
||||
│ ├─ benchmark-publish → nox -s benchmark (publish variant)
|
||||
│ ├─ build job → nox -s build
|
||||
│ └─ docker job → (Docker build, uses wheel from build job)
|
||||
│ ├─ e2e_tests job → nox -s e2e_tests
|
||||
│ ├─ coverage job → nox -s coverage_report (fail-under 97%)
|
||||
│ ├─ benchmark-regression → nox -s benchmark_regression
|
||||
│ ├─ benchmark-publish → nox -s benchmark (publish variant, push to master/develop only)
|
||||
│ ├─ build job → nox -s build
|
||||
│ └─ docker job → Docker build + smoke test
|
||||
│
|
||||
├─ REQUIRED FOR MERGE (status-check gate):
|
||||
│ ├─ lint ✓
|
||||
@@ -1283,15 +1331,19 @@ Complete nox session guide:
|
||||
│ ├─ security ✓
|
||||
│ ├─ unit_tests ✓
|
||||
│ └─ coverage ✓
|
||||
│ (integration_tests, e2e_tests, benchmark-regression are informational)
|
||||
│ (integration_tests, e2e_tests, benchmark-regression are informational only)
|
||||
│
|
||||
├─ RULES:
|
||||
│ ├─ ALWAYS use nox — never invoke behave/robot/pytest directly
|
||||
│ ├─ If a session is missing → add it to noxfile.py BEFORE using
|
||||
├─ UNIVERSAL RULES (apply to any language, not just Python/nox):
|
||||
│ ├─ ALWAYS use the task runner — never invoke test/lint/type-check tools directly
|
||||
│ │ Python/nox: never call `behave`, `robot`, `pyright`, or `ruff` directly
|
||||
│ │ Node.js: never call `jest`, `eslint`, or `tsc` directly — use `npm run <script>`
|
||||
│ │ Java/Gradle: never call JUnit directly — use `./gradlew test`
|
||||
│ │ Go: `go test` is idiomatic, but complex projects wrap it in `make` / `mage`
|
||||
│ ├─ If a session/script is missing → add it to the task runner config BEFORE using it
|
||||
│ └─ Test failure → immediately becomes blocking task; fix before moving on
|
||||
│
|
||||
└─ NIGHTLY QUALITY SESSIONS (run by nightly-quality.yml, not CI):
|
||||
└─ nox -s complexity (radon complexity analysis)
|
||||
└─ NIGHTLY QUALITY SESSIONS (nightly-quality.yml — not part of standard CI):
|
||||
└─ nox -s complexity (Radon code complexity analysis)
|
||||
```
|
||||
|
||||
### "Am I looking at a CI failure?"
|
||||
@@ -1306,54 +1358,57 @@ Diagnosing and fixing CI failures:
|
||||
│ └─ 4. The status-check job summarizes all required results
|
||||
│
|
||||
├─ WHICH JOBS ARE REQUIRED FOR MERGE?
|
||||
│ ├─ lint → Ruff linting + format check (nox -s lint, nox -s format -- --check)
|
||||
│ ├─ typecheck → Pyright (nox -s typecheck)
|
||||
│ ├─ security → Bandit + Semgrep + Vulture (nox -s security_scan, nox -s dead_code)
|
||||
│ ├─ unit_tests → Behave BDD tests (nox -s unit_tests)
|
||||
│ └─ coverage → Slipcover ≥ 97% (nox -s coverage_report)
|
||||
│ ├─ lint → linting + format check (Python/nox: nox -s lint, nox -s format -- --check)
|
||||
│ ├─ typecheck → static type checking (Python/nox: nox -s typecheck)
|
||||
│ ├─ security → security scan + dead code (Python/nox: nox -s security_scan, nox -s dead_code)
|
||||
│ ├─ unit_tests → BDD unit tests (Python/nox: nox -s unit_tests)
|
||||
│ └─ coverage → coverage ≥ 97% (Python/nox: nox -s coverage_report)
|
||||
│ Other jobs (integration_tests, e2e_tests, benchmark-regression) are informational
|
||||
│
|
||||
├─ DIAGNOSING SPECIFIC FAILURES:
|
||||
│ │
|
||||
│ ├─ lint failure
|
||||
│ │ ├─ Run: nox -s lint (see exact violations)
|
||||
│ │ ├─ Auto-fix: nox -s format
|
||||
│ │ ├─ Run the lint session to see exact violations (e.g. nox -s lint)
|
||||
│ │ ├─ Auto-fix where possible (e.g. nox -s format)
|
||||
│ │ └─ Remaining violations → fix manually
|
||||
│ │
|
||||
│ ├─ typecheck failure
|
||||
│ │ ├─ Run: nox -s typecheck (see Pyright errors)
|
||||
│ │ ├─ Fix ALL type errors — never add # type: ignore
|
||||
│ │ └─ Never disable Pyright in config files
|
||||
│ │ ├─ Run the type check session to see errors (e.g. nox -s typecheck)
|
||||
│ │ ├─ Fix ALL type errors — never add inline type suppression comments:
|
||||
│ │ │ Python: # type: ignore | TypeScript: // @ts-ignore | Java: @SuppressWarnings
|
||||
│ │ └─ Never disable the type checker in configuration files
|
||||
│ │
|
||||
│ ├─ security failure
|
||||
│ │ ├─ Run: nox -s security_scan (see bandit/semgrep findings)
|
||||
│ │ ├─ Run: nox -s dead_code (see vulture findings)
|
||||
│ │ ├─ Run the security scan session (e.g. nox -s security_scan)
|
||||
│ │ ├─ Run the dead code session (e.g. nox -s dead_code)
|
||||
│ │ ├─ Fix or suppress findings with proper justification comments
|
||||
│ │ └─ High-severity bandit findings → must be fixed, not suppressed
|
||||
│ │ └─ High-severity findings → must be fixed, not suppressed
|
||||
│ │
|
||||
│ ├─ unit_tests failure
|
||||
│ │ ├─ Run: nox -s unit_tests (see failing scenarios)
|
||||
│ │ ├─ Run the unit test session to see failing scenarios (e.g. nox -s unit_tests)
|
||||
│ │ ├─ Fix the failing step or the code it exercises
|
||||
│ │ └─ ⚠️ @tdd_expected_fail failure means bug was fixed without removing tag
|
||||
│ │ └─ ⚠️ @tdd_expected_fail failure means bug was fixed without removing the tag
|
||||
│ │
|
||||
│ ├─ coverage failure
|
||||
│ │ ├─ Run: nox -s coverage_report (see "COVERAGE OK" or "COVERAGE FAILED")
|
||||
│ │ ├─ Run the coverage session (e.g. nox -s coverage_report)
|
||||
│ │ ├─ Look for "COVERAGE OK" or "COVERAGE FAILED" in the output
|
||||
│ │ ├─ Look at coverage report for uncovered lines
|
||||
│ │ ├─ Add tests for uncovered paths
|
||||
│ │ └─ Exception: project owner approval required for exclusions
|
||||
│ │ └─ Exception: project owner approval required for any coverage exclusion
|
||||
│ │
|
||||
│ └─ TDD tag gate failure (in unit_tests or a dedicated gate)
|
||||
│ └─ TDD tag gate failure (in unit_tests or a dedicated CI gate)
|
||||
│ ├─ "@tdd_expected_fail still present on @tdd_issue_N" → remove the tag
|
||||
│ └─ "no @tdd_issue_N test found for bug #N" → TDD step was skipped
|
||||
│
|
||||
├─ AFTER FIXING
|
||||
│ ├─ Run the affected nox session locally to confirm fix
|
||||
│ ├─ Run nox (full suite) to ensure no regressions
|
||||
│ ├─ Run the affected task runner session locally to confirm the fix
|
||||
│ ├─ Run the full task runner suite to ensure no regressions (e.g. nox)
|
||||
│ └─ Push the fix — CI re-runs automatically
|
||||
│
|
||||
└─ NEVER:
|
||||
├─ Skip failing checks by force-pushing without fixing them
|
||||
├─ Use type: ignore to silence Pyright
|
||||
├─ Use inline type suppression comments to silence the type checker
|
||||
│ (Python: # type: ignore | TypeScript: // @ts-ignore | Java: @SuppressWarnings)
|
||||
└─ Use --no-verify to bypass pre-commit hooks
|
||||
```
|
||||
|
||||
@@ -1362,34 +1417,37 @@ Diagnosing and fixing CI failures:
|
||||
```
|
||||
File organization — every file has a canonical home:
|
||||
│
|
||||
├─ /src/cleveragents/
|
||||
├─ /src/<package>/
|
||||
│ ├─ Production source code ONLY
|
||||
│ ├─ Python packages, modules, and subpackages
|
||||
│ │ Example: src/myapp/ for a Python project named "myapp"
|
||||
│ │ src/main/java/com/example/ for a Java project
|
||||
│ │ src/ for a TypeScript project
|
||||
│ ├─ Source packages, modules, and components for the target language
|
||||
│ ├─ ⚠️ MUST NOT contain: tests, mocks, test data, documentation, examples
|
||||
│ └─ If you're tempted to put test/mock code here → put it in features/mocks/
|
||||
│ └─ If you're tempted to put test/mock code here → put it in the test mock directory
|
||||
│
|
||||
├─ /features/
|
||||
│ ├─ Behave BDD unit tests ONLY
|
||||
│ ├─ *.feature files (Gherkin scenarios)
|
||||
│ ├─ steps/ subdirectory (step definitions)
|
||||
│ └─ /features/mocks/ → ALL mocks, fakes, stubs, test doubles
|
||||
│ ⚠️ This is the ONLY place mocks are allowed
|
||||
├─ /features/ (project's BDD unit test directory — project uses Behave)
|
||||
│ ├─ BDD unit tests ONLY — Gherkin *.feature files + step definitions
|
||||
│ ├─ steps/ subdirectory — step definition files
|
||||
│ └─ /features/mocks/ → ALL mocks, fakes, stubs, test doubles for this project
|
||||
│ ⚠️ This is the ONLY place mocks are allowed in this project
|
||||
│ Note: other frameworks/languages may name this spec/, test/, tests/unit/, or __tests__/
|
||||
│
|
||||
├─ /robot/
|
||||
│ ├─ Robot Framework integration and e2e tests ONLY
|
||||
│ ├─ .robot files and .resource files
|
||||
├─ /robot/ (project's integration and e2e test directory — project uses Robot Framework)
|
||||
│ ├─ Integration and end-to-end tests ONLY — .robot and .resource files
|
||||
│ └─ ⚠️ No mocks allowed here (real services only)
|
||||
│ Note: other projects may name this tests/integration/, e2e/, cypress/, or test/e2e/
|
||||
│
|
||||
├─ /docs/
|
||||
│ ├─ Documentation and markdown files for MkDocs
|
||||
│ ├─ docs/specification.md → THE authoritative architecture spec
|
||||
│ ├─ Documentation and markdown files (project: MkDocs format)
|
||||
│ ├─ docs/specification.md → THE authoritative architecture specification
|
||||
│ └─ API docs, user guides, architecture docs, changelog
|
||||
│
|
||||
├─ /config/
|
||||
│ └─ Configuration files (not pyproject.toml — that stays in root)
|
||||
│ └─ Configuration files (not the project manifest — that stays in root)
|
||||
│
|
||||
├─ /scripts/
|
||||
│ ├─ Utility shell scripts (e.g., setup-dev.sh)
|
||||
│ ├─ Utility shell/automation scripts (e.g. setup-dev.sh)
|
||||
│ └─ ⚠️ MUST NOT contain: mock code, test data, production source
|
||||
│
|
||||
├─ /examples/
|
||||
@@ -1398,27 +1456,29 @@ File organization — every file has a canonical home:
|
||||
├─ /k8s/
|
||||
│ └─ Kubernetes Helm chart for server deployment
|
||||
│
|
||||
├─ ROOT LEVEL (project root only)
|
||||
│ ├─ pyproject.toml → all project configuration
|
||||
│ ├─ noxfile.py → all nox session definitions
|
||||
│ ├─ .pre-commit-config.yaml → pre-commit hooks
|
||||
│ ├─ robot.cfg → Robot Framework configuration
|
||||
├─ ROOT LEVEL (project root only — keep clean)
|
||||
│ ├─ Project manifest / build config:
|
||||
│ │ Python: pyproject.toml | Node.js: package.json | Java: build.gradle / pom.xml
|
||||
│ ├─ Task runner config:
|
||||
│ │ Python/nox: noxfile.py | Node.js: scripts in package.json | make: Makefile
|
||||
│ ├─ Pre-commit hooks config (e.g. .pre-commit-config.yaml)
|
||||
│ ├─ Test framework / runner config (e.g. robot.cfg, jest.config.js, pytest.ini)
|
||||
│ ├─ README, CONTRIBUTING, LICENSE, CHANGELOG, CONTRIBUTORS.md
|
||||
│ ├─ .forgejo/ → Forgejo Actions workflow definitions
|
||||
│ ├─ CI/CD workflow definitions (e.g. .forgejo/, .github/)
|
||||
│ └─ Other widely recognized root-level convention files
|
||||
│ ⚠️ NO arbitrary files in root — if it doesn't conventionally live there,
|
||||
│ put it in an appropriate subdirectory
|
||||
│
|
||||
└─ DECISION HEURISTIC
|
||||
├─ Is it production code? → /src/cleveragents/
|
||||
├─ Is it a BDD scenario or step? → /features/
|
||||
├─ Is it a mock/fake/stub? → /features/mocks/
|
||||
├─ Is it a Robot Framework test? → /robot/
|
||||
├─ Is it documentation? → /docs/
|
||||
├─ Is it a config file? → /config/
|
||||
├─ Is it a utility script? → /scripts/
|
||||
├─ Is it example code? → /examples/
|
||||
└─ Is it a Kubernetes resource? → /k8s/
|
||||
├─ Is it production code? → /src/<package>/
|
||||
├─ Is it a BDD scenario or step? → /features/ (or project's BDD test dir)
|
||||
├─ Is it a mock/fake/stub? → /features/mocks/ (or project's mock location)
|
||||
├─ Is it an integration/e2e test? → /robot/ (or project's integration test dir)
|
||||
├─ Is it documentation? → /docs/
|
||||
├─ Is it a config file? → /config/
|
||||
├─ Is it a utility script? → /scripts/
|
||||
├─ Is it example code? → /examples/
|
||||
└─ Is it a Kubernetes resource? → /k8s/
|
||||
```
|
||||
|
||||
### "Am I setting up my development environment?"
|
||||
@@ -1434,10 +1494,10 @@ Development environment setup (new contributor checklist):
|
||||
│ └─ This installs pre-commit hooks that run automatically on every commit
|
||||
│
|
||||
├─ STEP 3: Verify the setup
|
||||
│ ├─ nox (run all default sessions)
|
||||
│ ├─ Run the full task runner suite (Python/nox: nox)
|
||||
│ └─ All sessions must be green before you start work
|
||||
│
|
||||
├─ STEP 4: Install Commitizen (recommended)
|
||||
├─ STEP 4: Install Commitizen (recommended — works for any language project)
|
||||
│ ├─ npm install -g commitizen@2.8.6 cz-customizable@4.0.0
|
||||
│ └─ Use: git cz (instead of git commit — guides you through message format)
|
||||
│
|
||||
@@ -1446,24 +1506,29 @@ Development environment setup (new contributor checklist):
|
||||
│ ├─ docs/specification.md → architecture and design decisions
|
||||
│ └─ This skill file → procedural decision trees
|
||||
│
|
||||
├─ VERIFICATION CHECKLIST
|
||||
│ ├─ nox -s lint → green?
|
||||
│ ├─ nox -s typecheck → green?
|
||||
│ ├─ nox -s unit_tests → green?
|
||||
│ ├─ nox -s coverage_report → ≥ 97%?
|
||||
│ ├─ Pre-commit hooks installed? (git commit should trigger hooks)
|
||||
├─ VERIFICATION CHECKLIST (examples use Python/nox)
|
||||
│ ├─ Lint session → green? (nox -s lint)
|
||||
│ ├─ Type check session → green? (nox -s typecheck)
|
||||
│ ├─ Unit test session → green? (nox -s unit_tests)
|
||||
│ ├─ Coverage session → ≥ 97%? (nox -s coverage_report)
|
||||
│ ├─ Pre-commit hooks installed? (git commit should trigger hooks)
|
||||
│ └─ git cz available if Commitizen installed?
|
||||
│
|
||||
└─ WHAT TOOLS ARE USED
|
||||
├─ Hatch → project management (hatch env create, hatch build)
|
||||
├─ nox → task automation (ALWAYS use nox, never invoke tools directly)
|
||||
├─ pyproject.toml → all project configuration (single source)
|
||||
├─ Behave → BDD unit tests
|
||||
└─ WHAT TOOLS ARE USED (this project — Python ecosystem)
|
||||
├─ Hatch → Python project management (hatch env create, hatch build)
|
||||
├─ nox → task automation (ALWAYS use nox, never invoke tools directly)
|
||||
├─ pyproject.toml → all project configuration (single-source truth)
|
||||
├─ Behave → BDD unit tests (Gherkin feature files + step definitions)
|
||||
├─ Robot Framework + pabot → integration and e2e tests
|
||||
├─ Pyright → static type checking (strict, no suppressions ever)
|
||||
├─ ruff → linting and formatting
|
||||
├─ Commitizen → interactive commit message generation
|
||||
└─ pre-commit → automated quality hooks
|
||||
├─ Pyright → static type checking (strict, no suppressions ever)
|
||||
├─ ruff → linting and formatting
|
||||
├─ Slipcover → test coverage measurement (fail-under 97%)
|
||||
├─ Commitizen → interactive commit message generation
|
||||
└─ pre-commit → automated quality hooks
|
||||
|
||||
General principle (any language): use modern, idiomatic tooling for your
|
||||
ecosystem. Avoid legacy approaches (raw Makefiles, ad-hoc shell wrappers).
|
||||
All tooling should be from the current ecosystem and used as designed.
|
||||
```
|
||||
|
||||
### "Should this be an Issue, Epic, or Legendary?"
|
||||
@@ -1562,7 +1627,7 @@ Ticket type hierarchy decision:
|
||||
### "Am I choosing between Legacy and v3 plan workflow?"
|
||||
|
||||
```
|
||||
CleverAgents CLI plan workflow choice:
|
||||
Project-specific CLI plan workflow choice (CleverAgents project):
|
||||
│
|
||||
├─ THESE TWO SYSTEMS ARE MUTUALLY EXCLUSIVE — cannot be mixed
|
||||
│
|
||||
@@ -1583,14 +1648,14 @@ CleverAgents CLI plan workflow choice:
|
||||
│ └─ Apply changes: agents plan apply <PLAN_ID>
|
||||
│
|
||||
├─ LEGACY SYSTEM (deprecated — do not start new work here)
|
||||
│ ├─ Tell: agents tell -n "my-plan" "Devise a plan to..."
|
||||
│ ├─ Tell: agents tell -n "my-plan" "Devise a plan to..."
|
||||
│ ├─ Build: agents build
|
||||
│ └─ Apply: agents apply my-plan
|
||||
│
|
||||
├─ IDENTIFIER FORMATS
|
||||
│ ├─ V3: ULID — 26-character Crockford base32 string
|
||||
│ │ e.g. 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||||
│ └─ Legacy: human-readable name (e.g. "64-bit port plan")
|
||||
│ ├─ V3: ULID — 26-character Crockford base32 string
|
||||
│ │ e.g. 01HXM8C2ZK4Q7C2B3F2R4VYV6J
|
||||
│ └─ Legacy: human-readable name (e.g. "64-bit port plan")
|
||||
│
|
||||
├─ WHY THEY CANNOT BE MIXED
|
||||
│ ├─ Completely separate storage backends
|
||||
@@ -1620,9 +1685,10 @@ Release process:
|
||||
│ └─ From v3.0.0 onward: backwards compatibility must be maintained
|
||||
│
|
||||
├─ STEP 1: Verify everything is ready
|
||||
│ ├─ nox (full suite) → all green
|
||||
│ ├─ Full task runner suite → all green (e.g. nox)
|
||||
│ ├─ Changelog updated with all changes since last release
|
||||
│ ├─ Version number bumped in pyproject.toml
|
||||
│ ├─ Version number bumped in the project manifest
|
||||
│ │ (Python: pyproject.toml | Node.js: package.json | Java: build.gradle)
|
||||
│ └─ All required CI checks passing on master
|
||||
│
|
||||
├─ STEP 2: Create and push the version tag
|
||||
@@ -1630,10 +1696,10 @@ Release process:
|
||||
│ └─ git push origin v3.6.0
|
||||
│
|
||||
├─ STEP 3: release.yml workflow runs automatically
|
||||
│ ├─ Builds wheel via nox -s build
|
||||
│ ├─ Builds distributable artifact (Python/nox: nox -s build → wheel)
|
||||
│ ├─ Builds Docker image tagged with version + "latest"
|
||||
│ ├─ Pushes Docker image to container registry
|
||||
│ └─ Creates Forgejo release with wheel as downloadable artifact
|
||||
│ └─ Creates Forgejo release with artifact as downloadable file
|
||||
│
|
||||
├─ REQUIRED REPOSITORY SECRETS (must exist for release to succeed)
|
||||
│ ├─ CONTAINER_REGISTRY → Docker registry URL
|
||||
@@ -1662,8 +1728,8 @@ TDD issue-capture test requirements (detailed tag rules):
|
||||
│ └─ tdd/mN-<descriptive-name> (e.g. tdd/m3-shacl-crash)
|
||||
│
|
||||
├─ THE TEST ITSELF
|
||||
│ ├─ Framework: Behave (Gherkin scenario)
|
||||
│ ├─ Scenario must capture the buggy behavior
|
||||
│ ├─ Framework: BDD with Gherkin (project uses Behave — adapt for your BDD framework)
|
||||
│ ├─ Scenario must capture the buggy behavior:
|
||||
│ │ └─ Given the conditions that trigger the bug
|
||||
│ │ └─ When the action that causes the bug is performed
|
||||
│ │ └─ Then the assertion that SHOULD pass but currently FAILS
|
||||
@@ -1688,20 +1754,24 @@ TDD issue-capture test requirements (detailed tag rules):
|
||||
│ │ without removing this tag — catches premature success)
|
||||
│ └─ TEMPORARY — MUST be removed by the bug fix developer
|
||||
│
|
||||
├─ ASSERTION TYPE REQUIREMENT (critical)
|
||||
│ ├─ Steps that signal "bug still present" MUST fail via AssertionError
|
||||
├─ ASSERTION TYPE REQUIREMENT (critical — applies to any language)
|
||||
│ ├─ Steps that signal "bug still present" MUST fail via the language's
|
||||
│ │ assertion failure type — NOT via runtime or infrastructure exceptions
|
||||
│ ├─ Python (this project):
|
||||
│ │ ├─ Use: assert some_condition, "message"
|
||||
│ │ └─ Use: raise AssertionError("bug still present")
|
||||
│ ├─ ⚠️ DO NOT USE: ValueError, RuntimeError, OSError, or any non-assertion
|
||||
│ │ exceptions to represent expected bug failures
|
||||
│ └─ Non-assertion exceptions are NOT inverted — they are infrastructure errors
|
||||
│ │ ⚠️ Do NOT use: ValueError, RuntimeError, OSError, or other non-assertion exceptions
|
||||
│ ├─ Java: throw new AssertionError(...) — not RuntimeException
|
||||
│ ├─ JavaScript/TS: throw new assert.AssertionError(...) — not Error or TypeError
|
||||
│ └─ The rule is universal: assertion failures are inverted by the TDD hook;
|
||||
│ runtime/infrastructure exceptions are NOT inverted and will break the suite
|
||||
│
|
||||
├─ TAG VALIDATION RULES (CI enforces all of these):
|
||||
│ ├─ @tdd_issue_N present → @tdd_issue MUST also be present
|
||||
│ ├─ @tdd_expected_fail present → @tdd_issue AND @tdd_issue_N MUST be present
|
||||
│ └─ Missing any required tag → CI rejects the test
|
||||
│
|
||||
├─ EXAMPLE — before bug fix:
|
||||
├─ EXAMPLE — before bug fix (Python/Behave):
|
||||
│ @tdd_issue @tdd_issue_123 @tdd_expected_fail
|
||||
│ Scenario: Bug #123 - SHACL validation rejects valid graph
|
||||
│ Given a valid resource graph
|
||||
@@ -1717,7 +1787,7 @@ TDD issue-capture test requirements (detailed tag rules):
|
||||
│
|
||||
└─ MERGING THE TDD PR
|
||||
├─ CI passes because @tdd_expected_fail inverts the result
|
||||
├─ Reviewer checks: test quality, correct tagging, AssertionError usage
|
||||
├─ Reviewer checks: test quality, correct tagging, correct assertion type usage
|
||||
├─ Merge to master (normal PR process)
|
||||
└─ Close the TDD issue; bug issue remains open (depends on bug fix PR)
|
||||
```
|
||||
@@ -1756,7 +1826,7 @@ TDD issue-capture test requirements (detailed tag rules):
|
||||
| Issue ↔ PR dependency direction | **PR blocks issue; issue depends on PR** | CONTRIBUTING.md |
|
||||
| Epic minimum children | **2 child issues** | CONTRIBUTING.md |
|
||||
| Legendary minimum children | **2 child Epics** | CONTRIBUTING.md |
|
||||
| TDD expected-fail exception type | **AssertionError only** (not ValueError/RuntimeError/etc.) | CONTRIBUTING.md |
|
||||
| TDD assertion failure type | **Language assertion type only** (Python: AssertionError; not runtime exceptions) | CONTRIBUTING.md |
|
||||
|
||||
---
|
||||
|
||||
@@ -1766,12 +1836,12 @@ TDD issue-capture test requirements (detailed tag rules):
|
||||
|----------|-------|--------|
|
||||
| `references/commits/` | README | Conventional Changelog, atomic commits, pre-commit hooks |
|
||||
| `references/pull-requests/` | README | PR checklist, review process, merge criteria |
|
||||
| `references/testing/` | README | Behave, Robot Framework, 97% threshold, TDD, mock placement |
|
||||
| `references/testing/` | README | BDD/Behave (unit), Robot Framework (integration), 97% threshold, TDD, mock placement |
|
||||
| `references/issue-tracking/` | README | Full issue guide, label system, ticket states, dependencies |
|
||||
| `references/sprints/` | README | Sprint structure, 6-stage triaging, poker points, MoSCoW |
|
||||
| `references/code-style/` | README | SOLID, programming patterns, error handling, Pyright, LangChain |
|
||||
| `references/code-style/` | README | SOLID, programming patterns, error handling, static type checking, LangChain/LangGraph |
|
||||
| `references/security/` | README | gopass, Yubikey rules, encryption policy, code signing |
|
||||
| `references/information/` | README | Stamp levels, document authoring, traceability, email conventions |
|
||||
| `references/organizational/` | README | C.O.C. org structure, ELB, OCRB, 12 committees, reviews |
|
||||
| `references/project-tools/` | README | nox sessions (all), CI pipeline (all jobs), release process, Hatch |
|
||||
| `references/project-tools/` | README | task runner sessions (nox), CI pipeline (all jobs), release process, Hatch |
|
||||
| `references/open-source/` | README | FOSS governance, open standards mandate, POSIX |
|
||||
|
||||
Reference in New Issue
Block a user