Enhance quality requirements with semantic anchors and clarity

.agents/skills/openfasttrace-spec-driven-development/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: oft-spec-driven-development
+description: Support spec-driven development in projects that use OpenFastTrace, a system-requirements document in `doc/system_requirements.md`, an arc42-style design in `doc/design.md`, and per-issue task plans in `doc/changesets/`. Use when AI agent must turn a new GitHub issue or Jira ticket into a changeset plan, update traced requirements and design before or alongside code, and keep all implementation and verification work aligned with the project's quality requirements.
+---
+
+# OFT Spec-Driven Development
+
+Work from specification to implementation. Treat the requirements, design, and quality documents as the source of truth for both planning and changes.
+
+## Project Contract
+
+Use these repository conventions unless the user explicitly says this project differs:
+
+- System requirements live in `doc/system_requirements.md` and use OpenFastTrace notation.
+- Design lives in `doc/design.md` and its referenced arc42 chapters under `doc/design/`.
+- Per-issue implementation plans live in `doc/changesets/` using `<issue-number>-<short-kebab-title>.md`.
+- Quality requirements are authoritative for code, tests, tracing, and build gates. See `doc/design/quality_requirements.md` or `doc/spec/design/quality_requirements.md`.
+
+## OFT Reference
+
+For OFT syntax, tracing behavior, selective tracing, and common error handling, read the upstream OpenFastTrace skill first:
+
+`https://raw.githubusercontent.com/itsallcode/openfasttrace/refs/heads/main/skills/openfasttrace-skill/SKILL.md`
+
+Do not restate OFT rules from memory when the upstream reference is available. Use it as the normative workflow for:
+
+- specification item syntax and IDs
+- `Needs`, `Covers`, forwarding, and coverage tags
+- selective tracing and trace interpretation
+- diagnosing broken trace links
+
+## Operating Mode
+
+When the user gives you a new issue link, derive the work plan from:
+
+1. the issue or ticket itself
+2. `doc/system_requirements.md`
+3. `doc/design.md` and the relevant linked design chapters
+4. the quality requirements document
+5. the current code and tests
+
+Do not jump straight to code. First determine whether the issue changes:
+
+- user-visible behavior
+- traced requirements or scenarios
+- design decisions, building blocks, runtime behavior, or constraints
+- verification expectations from the quality requirements
+
+If the ticket conflicts with the existing specification or design, surface that conflict and repair the documents before or together with implementation.
+
+## Required Workflow
+
+### 1. Read Before Planning
+
+Before drafting or editing a changeset, inspect:
+
+- `doc/system_requirements.md`
+- `doc/design.md`
+- the specific design chapters relevant to the issue
+- `doc/design/quality_requirements.md`
+- `doc/changesets/README.md`
+- existing changesets that touch the same feature area
+
+Read code only after you understand the spec and design impact.
+
+### 2. Create Or Update The Changeset
+
+For a new issue, create `doc/changesets/<issue-number>-<short-kebab-title>.md`.
+
+Use the established repository style:
+
+- title with tracker reference and short summary
+- `Goal`
+- `Scope` with explicit in-scope and out-of-scope bullets
+- `Design References`
+- optional `Strategy` when the issue needs implementation direction
+- `Task List`
+
+Keep the task list ordered. Put specification and design work before production-code work unless the issue is strictly internal and does not affect traced artifacts.
+
+### 3. Derive The Plan From The Spec
+
+When building the task list, map the issue onto the requirement hierarchy from the quality requirements:
+
+- `feat`
+- `req`
+- `scn`
+- `dsn`
+- `impl`
+- `utest` or `itest`
+
+Use that mapping to decide what must change:
+
+- If behavior changes for users, update or add `req` and `scn` items in `doc/system_requirements.md`.
+- If architecture or technical behavior changes, update or add `dsn` items and relevant arc42 design sections.
+- If a lower layer adds no new information, prefer OFT forwarding instead of redundant new items.
+- Ensure each runtime design item covers only one scenario unless forwarding is the better fit.
+
+### 4. Treat Quality Requirements As Non-Negotiable
+
+Every plan and implementation must satisfy `doc/design/quality_requirements.md`.
+
+Always derive verification tasks from that document, including as applicable:
+
+- clean trace results for the requirement and design artifact types in scope
+- tests that follow the naming, assertion, and parameter-validation rules
+- coverage expectations
+- plugin verification and build checks
+- dependency-policy constraints
+- static-analysis and security gates
+
+If an issue required violating a documented quality rule, stop and raise it explicitly instead of silently proceeding.
+
+### 5. Implement In Spec-First Order
+
+Preferred order:
+
+1. requirements updates
+2. design updates
+3. changeset task-plan update
+4. production code
+5. tests
+6. OFT trace and project verification
+
+For small internal refactors, you may keep the docs unchanged only when the traced requirements and design remain fully accurate.
+
+## Changeset Template
+
+Use this template and adapt it to the issue:
+
+```md
+# GH-<number> <title>
+
+## Goal
+
+<What the issue achieves and why it matters.>
+
+## Scope
+
+In scope:
+
+* <planned change>
+
+Out of scope:
+
+* <explicit non-goal>
+
+## Design References
+
+* [System Requirements](<path-to-specs>/system_requirements.md)
+* [Quality Requirements](<path-to-specs>/design/quality_requirements.md)
+* [<Relevant design chapter>](<path-to-specs>/design/<chapter>.md)
+
+## Strategy
+
+<Only include when useful. Describe the intended implementation direction.>
+
+## Task List
+
+- [ ] Create and checkout a new Git branch `<issue-type>/<issue-number>-<issue-title-lower-kebab-case>`
+
+### Requirements And Design
+
+- [ ] <system requirements update>
+- [ ] Stop and ask user for a review of the system requirements
+- [ ] <design update>
+- [ ] Stop and ask user for a review of the design
+
+### Implementation
+
+- [ ] <production code task>
+
+### Verification
+
+- [ ] <tests derived from quality requirements>
+- [ ] Keep the OpenFastTrace trace clean
+- [ ] Keep required build and plugin verification tasks green
+
+### Update user documentation
+
+- [ ] Update the end user documentation in `README.md` and / or `doc/user_guide/user_guide.md`
+
+## Version and Changelog Update
+
+- [ ] Raise the version to 0.3.0 (this is a feature release)
+- [ ] Write the changelog entry for 0.3.0
+```
+
+Keep verification items concrete. Do not leave them as generic "run tests" placeholders when the quality requirements demand more specific checks.
+
+## Issue Intake Rules
+
+When the user provides a tracker link:
+
+- extract the issue number for the changeset filename
+- derive a short kebab-case title from the issue title
+- summarize the requested outcome in repository terms
+- identify impacted requirements, scenarios, design sections, code areas, and tests
+- draft the changeset before substantial implementation
+
+If the issue text is unavailable, ask the user for the issue content or a short summary. Do not invent requirements from the URL alone.
+
+## Editing Rules
+
+- Preserve existing OFT IDs unless the semantics changed.
+- When semantics change, revise the item thoughtfully instead of making arbitrary ID churn.
+- Keep requirements user-facing and design technical; do not duplicate the same text in both places.
+- Prefer precise task items over broad epics in changesets.
+- Keep comments in code minimal and let naming carry intent, consistent with the quality requirements.
+- Avoid adding dependencies unless a documented design decision approves them.
+
+## Verification Rules
+
+Before closing work, verify at the level the issue changed:
+
+- OFT artifacts stay syntactically valid and traceable.
+- Requirement, scenario, design, implementation, and tests remain consistent.
+- Automated tests cover the new behavior at the correct level.
+- Repository quality gates required by `doc/design/quality_requirements.md` are either run or explicitly called out as not run.
+
+If you cannot run a required verification step, state that clearly in the final report and leave the changeset task unchecked.

doc/changes/changes.md

@@ -1,5 +1,6 @@
 # Changes
 
+* [4.3.1](changes_4.3.1.md)
 * [4.3.0](changes_4.3.0.md)
 * [4.2.3](changes_4.2.3.md)
 * [4.2.2](changes_4.2.2.md)

doc/changes/changes_4.3.1.md

@@ -0,0 +1,13 @@
+# OpenFastTrace 4.3.0, released 2026-05-??
+
+Code name: Spec-driven Development Skill
+
+## Summary
+
+In this release we added the OpenFastTrace Spec-driven Development Skill. The skill guides AI agents through turning a GitHub issue into a changeset plan that can be reviewed before it gets executed by the user. The process uses a spec-driven development approach backed by an OFT spec.
+
+We also moved the skills to `.agents/skills` for best cross-vendor compatibility.
+
+## Documentation
+
+* Added changeset skill

doc/spec/design.md

@@ -1074,6 +1074,10 @@ Covers:
 
 Needs: impl
 
+# Quality Requirements
+
+See [Quality Requirements](design/quality_requirements.md).
+
 # Design Decisions
 
 ## How do we Implement the Command Line Interpreter

doc/spec/design/quality_requirements.md

@@ -0,0 +1,133 @@
+# Quality Requirements
+
+This chapter documents architecture-relevant quality requirements and technical quality goals.
+
+User-facing acceptance scenarios are defined in [System Requirements](../system_requirements.md).
+
+Terms such as `plugin`, `OpenFastTrace`, and `OFT` use the definitions from [System Requirements](../system_requirements.md).
+
+## Requirement Quality
+
+We have the following requirement hierachy in this project:
+
+| Document            | Level | Artifact types | Meaning                                                                 | Covers                 |
+|---------------------|-------|----------------|-------------------------------------------------------------------------|------------------------|
+| System Requirements | 1     | `feat`         | Top level feature as you would find on a product sheet (limited number) |                        |
+|                     | 2     | `req`          | High level requirement                                                  | `feat`                 |
+|                     | 3     | `scn`          | Given-when-then scenario                                                | `req`                  |
+| Design              | 3     | `constr`       | Technical constraint                                                    |                        |
+|                     | 4     | `dsn`          | Design requirement                                                      | `req`, `scn`, `constr` |
+| Production Code     | 5     | `impl`         | Implementation                                                          | `dsn`                  |
+| Test Code           | 5     | `utest`        | Unit test                                                               | `dsn`                  |
+|                     | 5     | `itest`        | Integration test                                                        | `dsn`                  |
+
+Runtime design requirements `dsn` can only cover on scenario at a time `scn`.
+
+Use OFT's forwarding notation if a technical requirement does not add new information to a user-level requirement.
+
+## Code Quality
+
+The following rules are written for both human contributors and coding agents. The anchor names are short reminders; the rules below are normative.
+
+### Production Code Rules
+
+#### Clean Architecture
+
+1. New code must keep dependencies pointing toward stable abstractions and module APIs instead of concrete implementation details.
+2. Code must be testable through public or package-visible seams already used in the code base. Do not require global state, hidden environment coupling, or hard-wired I/O to test behavior.
+3. Names and structure must reveal intent. If the design is hard to explain without a long comment, simplify the design first.
+
+#### KISS
+
+1. Choose the simplest implementation that satisfies the requirement and existing design constraints.
+2. Avoid speculative abstractions, premature generalization, and configuration options that are not required by the current requirements or design.
+3. Keep methods and control flow small enough that the behavior can be understood locally.
+
+#### DRY
+
+1. Do not copy-paste production logic across classes or modules.
+2. Extract shared behavior when duplication would cause multiple sources of truth for the same rule, algorithm, or parsing logic.
+3. Do not introduce an abstraction only to remove a few repeated lines when that abstraction makes the code harder to read.
+
+#### Explicit Code
+
+1. Use descriptive package, class, method, and variable names.
+2. Do not introduce new non-domain abbreviations. Established domain or technical abbreviations such as `OFT`, `CLI`, `XML`, or similar widely understood terms are allowed.
+3. Prefer code that explains itself through naming and structure.
+4. Comments are only allowed when they capture intent or context that the code cannot express clearly on its own.
+
+#### Thread Safe
+
+1. Prefer immutable objects and side-effect-free methods.
+2. Avoid shared mutable state unless it is required by the design.
+3. If mutable shared state is necessary, synchronization and ownership must be explicit in the code and justified by the implementation context.
+
+#### OWASP
+
+1. Keep the OWASP anchor as a secure-coding reminder and apply the following minimum controls:
+2. Validate untrusted input at module boundaries.
+3. Reject invalid, malformed, or unexpected input explicitly.
+4. Avoid unsafe file, path, process, deserialization, reflection, or XML handling patterns.
+5. Do not log secrets, credentials, or other sensitive data.
+6. When security-relevant behavior changes, add or update tests that cover the expected safe behavior.
+
+### Test Rules
+
+#### DAMP
+
+1. Optimize tests for readability over deduplication.
+2. Small duplication of literals or setup is allowed when it makes the test easier to understand.
+3. Use parameterized tests when the same behavior must be verified against multiple input and output combinations.
+4. Extract helpers, builders, or matchers only when they remove repeated test logic or significantly reduce noisy setup.
+
+#### BDD
+
+1. Tests must describe behavior in Given-When-Then form.
+2. The structure may be expressed through method naming, local variable naming, whitespace, or short comments.
+3. Each test must make the precondition, action, and expected outcome easy to identify.
+
+#### Red-Green-Clean
+
+1. For behavior changes, write or update the test before changing production code.
+2. The new or changed test must fail for the expected reason before production code is changed to satisfy it.
+3. Only after the failing test exists may production code be written or changed to make the test pass.
+4. After the test passes, refactor as needed while keeping the tests green.
+
+#### Test Quality
+
+1. Each test should verify one logical expectation where possible.
+2. If multiple assertions are required to validate one behavior, group them with `assertAll`.
+3. Prefer known-good constants and explicit expected values over re-implementing the production algorithm in the test.
+4. If a test constant needs explanation, add a short comment that explains why the value matters.
+5. Parameter validation tests are required when invalid-input handling or boundary behavior is non-trivial.
+6. When parameter validation is tested, cover both valid and invalid inputs and keep them in separate test methods or parameterized test groups.
+7. When exceptions are asserted, verify both the exception type and the relevant message content.
+
+### Java Implementation Rules
+
+1. Document externally consumed APIs with JavaDoc. This includes public interfaces, abstract classes, and public methods that form part of an externally consumed API.
+2. JavaDoc must describe purpose, parameters, return values, and observable side effects when they exist.
+3. Declare method parameters as `final`.
+4. Output parameters are only allowed when required by external libraries.
+5. Prefer explicit types over `var`.
+
+### Java Test Rules
+
+1. Use Hamcrest matchers for assertions.
+2. Extract repeated complex assertions into dedicated matcher classes when that improves readability.
+
+## Dependency Policy
+
+Additional libraries are not allowed by default. Any new third-party dependency requires an explicit design decision and approval before it is added to the build.
+
+## Static Analysis And Security Gates
+
+Static code analysis runs in SonarQube Cloud and acts as a build breaker. A failing quality gate blocks integration until the reported issues are resolved or an approved exception exists.
+
+Dependency vulnerability monitoring runs through GitHub Dependabot instead of the Gradle build. Dependabot alerts provide the repository's vulnerability check for known vulnerable dependencies, while local and CI builds no longer run OSS Index as an immediate build-breaking gate.
+
+OpenFastTrace tracing runs as a build breaker for the specification artifacts in scope. The trace stays clean for the requirement and design artifact types used by the project.
+
+## Testability And Coverage
+
+Path coverage across the code base stays at or above 80%. Coverage below that threshold fails the build unless a documented exception is accepted in advance.

parent/pom.xml

@@ -10,7 +10,7 @@
     <description>Free requirement tracking suite</description>
     <url>https://github.com/itsallcode/openfasttrace</url>
     <properties>
-        <revision>4.3.0</revision>
+        <revision>4.3.1</revision>
         <java.version>17</java.version>
         <junit.version>6.1.0-M1</junit.version>
         <junit.version>6.0.3</junit.version>