diff --git a/skills/openfasttrace-reverse-specs/SKILL.md b/.agents/skills/openfasttrace-reverse-specs/SKILL.md similarity index 100% rename from skills/openfasttrace-reverse-specs/SKILL.md rename to .agents/skills/openfasttrace-reverse-specs/SKILL.md diff --git a/skills/openfasttrace-reverse-specs/agents/openai.yaml b/.agents/skills/openfasttrace-reverse-specs/agents/openai.yaml similarity index 100% rename from skills/openfasttrace-reverse-specs/agents/openai.yaml rename to .agents/skills/openfasttrace-reverse-specs/agents/openai.yaml diff --git a/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/architecture_decisions.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/building_block_view.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/building_block_view.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/building_block_view.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/building_block_view.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/constraints.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/constraints.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/constraints.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/constraints.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/context_and_scope.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/crosscutting_concepts.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/deployment_view.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/deployment_view.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/glossary.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/glossary.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/glossary.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/glossary.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/open_issues.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/open_issues.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/open_issues.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/open_issues.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/quality_requirements.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/risks_and_technical_debt.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/runtime_view.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/runtime_view.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/runtime_view.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/runtime_view.md diff --git a/skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md b/.agents/skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design/solution_strategy.md diff --git a/skills/openfasttrace-reverse-specs/assets/design_index_template.md b/.agents/skills/openfasttrace-reverse-specs/assets/design_index_template.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/design_index_template.md rename to .agents/skills/openfasttrace-reverse-specs/assets/design_index_template.md diff --git a/skills/openfasttrace-reverse-specs/assets/system_requirements_template.md b/.agents/skills/openfasttrace-reverse-specs/assets/system_requirements_template.md similarity index 100% rename from skills/openfasttrace-reverse-specs/assets/system_requirements_template.md rename to .agents/skills/openfasttrace-reverse-specs/assets/system_requirements_template.md diff --git a/skills/openfasttrace-reverse-specs/references/evidence_checklist.md b/.agents/skills/openfasttrace-reverse-specs/references/evidence_checklist.md similarity index 100% rename from skills/openfasttrace-reverse-specs/references/evidence_checklist.md rename to .agents/skills/openfasttrace-reverse-specs/references/evidence_checklist.md diff --git a/.agents/skills/openfasttrace-spec-driven-development/SKILL.md b/.agents/skills/openfasttrace-spec-driven-development/SKILL.md new file mode 100644 index 00000000..9241c46c --- /dev/null +++ b/.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 `-.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/-.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- + +## 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 + +## 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. diff --git a/doc/changes/changes.md b/doc/changes/changes.md index 4e1d9ffc..40f04ad6 100644 --- a/doc/changes/changes.md +++ b/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) diff --git a/doc/changes/changes_4.3.1.md b/doc/changes/changes_4.3.1.md new file mode 100644 index 00000000..ee4db32f --- /dev/null +++ b/doc/changes/changes_4.3.1.md @@ -0,0 +1,13 @@ +# OpenFastTrace 4.3.0, released 2026-05-11 + +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 diff --git a/doc/spec/design.md b/doc/spec/design.md index b30bc7f6..e2aa5250 100644 --- a/doc/spec/design.md +++ b/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 diff --git a/doc/spec/design/quality_requirements.md b/doc/spec/design/quality_requirements.md new file mode 100644 index 00000000..498a6f69 --- /dev/null +++ b/doc/spec/design/quality_requirements.md @@ -0,0 +1,94 @@ +# 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: + +1. `feat`: Top level feature as you would find on a product sheet (limited number) +2. `req`: High level requirement +3. `scn`: Given-when-then scenario +4. `dsn`: Design requirement + `constr`: Technical constraint +5. `impl`: Implementation + `utest`: Unit test + `itest`: Integration test + +Runtime design requirements `dsn` can only cover on scenario at a time `scn`. You can use OFT's forwarding notation if a technical requirement does not add new information to a user scenario. + +## Code Quality + +1. Production code and test code follow clean-code principles. +2. The implementation prefers speaking names over explanatory comments. Comments are only acceptable when intent cannot be expressed clearly in code. +3. Abbreviations are only used where they are guaranteed common (meaning everyone knows them) otherwise all symbol names are written out. +4. Methods avoid side effects where possible. +5. Methods stay short and keep cyclomatic complexity low. When behavior grows beyond a small, readable unit, the design is refactored into smaller collaborating types or methods. +6. When the cyclomatic complexity is too high, use extract method refactoring. +7. APIs (not implementation) are documented with JavaDoc: interfaces, abstract classes, methods, parameters, return values, side effects (if any), purpose +8. All objects that can be, are immutable. +9. The implementation prefers static object allocation over dynamic allocation where possible. +10. All method parameters are final. Output parameters are only allowed when they are used in external libraries. + +### Test Code Guideline + +1. Test method names follow the given-when-then naming principle. +2. Method parameters are final. +3. The project uses Hamcrest matchers. +4. If possible each test method has only a single assert. +5. If multiple asserts are necessary and the latter asserts are not a follow-up symptom of the previous ones, the asserts must be wrapped in `assertAll`. +6. When exceptions are asserted, then both type and message are validated. +7. Where possible similar tests are bundled into parameterized tests (e.g., when multiple variants of input are tested against the same implementation method). +8. Prefer parameterized tests over tests that exercise different scenarios of the same method under test with multiple asserts. +9. Parameter validation is tested with multiple valid and invalid inputs. Testing valid and invalid input is done in separate test methods. + +## Dependency Policy + +The plugin uses the minimum set of dependencies required for: + +* building and running a JetBrains plugin +* integrating the OpenFastTrace library + +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. + +The Gradle dependency verification metadata in `gradle/verification-metadata.xml` is committed to source control. Maintainers update and review this metadata whenever dependency declarations, Gradle plugin versions, the IntelliJ Platform version, or other build inputs change the resolved dependency artifacts. The standard update command is `./gradlew --write-verification-metadata sha256 help`. + +Generated local IntelliJ Platform Ivy metadata for bundled plugin and module artifacts is trusted without checksum verification because the IntelliJ Platform Gradle Plugin can generate environment-specific Ivy descriptors for the local IntelliJ Platform artifact repository. This exception applies only to `ivy-*.xml` descriptors in the `bundledPlugin` and `bundledModule` groups. Resolved JAR artifacts remain checksum verified. + +## 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. + +The Gradle build applies the latest OpenFastTrace Gradle plugin version approved for the project and executes `traceRequirements` locally and in CI through the standard `check` lifecycle. + +## Testability And Coverage + +Automated tests use JUnit 5 together with Hamcrest matchers. + +IntelliJ Platform light fixture tests may keep a JUnit 4 compatibility dependency when JetBrains test base classes still require the legacy `TestCase` API. + +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. + +The architecture favors testable units with clear boundaries so the coverage target can be met without relying mainly on brittle UI-level tests. + +Automated plugin testing follows the IntelliJ Platform test strategy and uses real platform components in a headless environment instead of extensive mocking. Most plugin behavior is verified as model-level functional tests against test data files and expected results. + +Plugin tests prefer light platform tests whenever possible because they reuse the project setup and run faster. Tests for plugin logic without Java-specific PSI use fixtures or base classes equivalent to `BasePlatformTestCase`. Heavier project-scoped tests are reserved for behavior that requires a fresh project, multiple modules, or project-level services that cannot be covered with light tests. + +Editor-facing features such as syntax highlighting, inspections, annotators, references, and navigation use the IntelliJ test fixtures and test data conventions. Highlighting tests store expected results in test files and verify them with the platform highlighting fixture support. + +End-to-end IDE startup and workflow checks use dedicated integration tests with the IntelliJ Platform Starter and Driver infrastructure. These tests run from a separate integration test task against the built plugin distribution, verify that the plugin loads into the target IDE, and cover only a small number of critical workflows because the UI driver APIs remain slower and more brittle than model-level tests. + +Continuous integration runs plugin-specific verification tasks in addition to ordinary automated tests. The build verifies plugin packaging and descriptor validity and runs IntelliJ Plugin Verifier checks against the supported IDE builds to detect binary compatibility problems early. + +## Platform Compatibility + +The required Java version follows the standard Java requirement of the targeted JetBrains platform version. The project does not introduce a language level or bytecode target that exceeds that platform requirement. diff --git a/parent/pom.xml b/parent/pom.xml index b69bc877..eec6434a 100644 --- a/parent/pom.xml +++ b/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> diff --git a/skills/openfasttrace-skill/SKILL.md b/skills/openfasttrace-skill/SKILL.md deleted file mode 100644 index 61e10644..00000000 --- a/skills/openfasttrace-skill/SKILL.md +++ /dev/null @@ -1,226 +0,0 @@ -### OpenFastTrace (OFT) Claude Skill - -OpenFastTrace (OFT) is a requirement tracing suite. This skill enables AI coding agents to author specification files, run traces, and perform selective tracing for different levels of the project hierarchy. - -OFT uses text files (Markdown, RST) for specification and code markers to represent coverage links. These markers are embedded in comments within source code, tests, and configuration files. OFT scans files or directories and detects specification documents and coverage. It calculates a network of requirements and coverage and reports the results. - -#### Writing Specification Files Correctly - -OFT uses Markdown with a specific syntax for specification items. "Specification Item" is the term that OFT uses to refer to a requirement, feature, design, or any other artifact that needs to be traced. - -**Specification Item ID Format:** -`<artifact-type>~<name>~<revision>` - -**Common Artifact Types:** -- `feat` (feature), `req` (requirement), `arch` (architecture), `dsn` (design) -- `impl` (implementation), `utest` (unit test), `itest` (integration test), `stest` (system test) - -While these are found in many projects, OFT allows users to use their own artifact types. Artifact types require no declaration. If a new artifact type is used, OFT will automatically recognize and support it. - -**Markdown Syntax Example:** -```markdown -### Requirement Title -`req~requirement-id~1` - -This is the description of the requirement. It can be multi-line. - -Rationale: - -This is why this requirement exists. - -Status: approved - -Needs: dsn - -Covers: -- `feat~feature-id~1` - -Tags: Security, Backend -``` - -**Key Keywords:** -- `Status`: `draft`, `proposed`, `approved`, `rejected` -- `Covers`: List of items this item provides coverage for (use bullet points). -- `Needs`: Artifact types required to cover this item (comma-separated or list). -- `Depends`: List of items this item depends on (not for coverage). -- `Rationale`, `Comment`: Informative text blocks. -- `Tags`: Comma-separated labels for filtering. - -**Status of a Specification Item** -By default an item is in status `approved`. This is for projects that use their specs to always reflect the status quo. If a project wants to use a specification as a planning tool for future work, it can use `draft` or `proposed` status. `rejected` is reserved for specification items that were explicitly rejected but should remain documented in the specification. - -**Forwarding (Shorthand):** -To forward a requirement to lower levels without a new item: -`arch --> dsn : req~web-ui-uses-corporate-design~1` - -This shorthand is used whenever a specification layer does not add new information to the covered specification item. As an example, if the user requirement says a report should be produced as PDF-A, then the designer can decide that they have nothing to add to that requirement. - -**Source Code Tags:** -Embed coverage in source code comments: -``` -// [impl->dsn~validate-authentication-request~1] -``` - -The comment character depends on the programming language. For example, in Java, JavaScript, C++ and so on it is `//`, in Python or shell scripts it is `#`. The comment character itself is ignored by OFT and only used to prevent the programming language from interpreting an OFT coverage tag as regular code. - -#### Importers and File Support - -OFT uses different **importers** to read various file formats and extract specification items or coverage links. It automatically selects the appropriate importer based on the file extension (suffix). - -* **Markdown Importer** (`.md`, `.markdown`): The primary importer for specification documents authored in Markdown. -* **Tag Importer**: Scans source code and configuration files for coverage tags (e.g., `// [impl->dsn~id~1]`) embedded in comments. It supports a wide range of programming and markup languages, including: - - **Languages**: (`java`, `py`, `cpp`, `c`, `cs`, `js`, `ts`, `sh`, `bash`, `zsh`, `php`, `pl`, `pm`, `go`, `groovy`, `lua`, `r`, `rs`, `swift`, `sql`). - - **Configurations**: (`json`, `yaml`, `yml`, `toml`, `proto`, `tf`, `cfg`, `conf`, `ini`). - - **Markup/Models**: (`html`, `xhtml`, `puml`, `plantuml`). -* **SpecObject Importer** (`.xml`, `.oreqm`): Used for ReqM2/SpecObject XML files. It automatically identifies `.xml` files containing a `<specdocument` header. -* **reStructuredText Importer** (`.rst`): For specification items authored in reStructuredText. -* **Zip Importer** (`.zip`): Allows OFT to trace contents of compressed ZIP files. - -#### Installing OFT - -OFT is available as a standalone executable JAR. To install OFT, download the latest release from the [OFT GitHub repository](https://github.com/itsallcode/openfasttrace/releases) and place the JAR file in a directory accessible to your LLM. - -Always use the latest release. - -#### Running OFT - -OFT is an executable JAR. You run oft from Java by executing the JAR file with the `java -jar` command. - -```shell -java -jar openfasttrace-<major.minor.fix>.jar <switches> -``` - -Replace the version number with the actual version of the downloaded jar. - -If you have a code interpreter or shell tool available, use it. Otherwise, always generate the command for the user to run manually. - -The examples below assume a wrapper script called `oft` in the binary path exists. In the following part of this skill description we assume that this script is available in the binary path. This is just a shorthand for `java -jar openfasttrace-<major.minor.fix>.jar <switches>` though, so that variant is equally viable. - -OFT has a trace mode and an exporter mode. The trace mode traces the requirement network and reports the results. The exporter mode exports the specification items in an exchange format. - - -#### Save Operation (Dry Run) - -Requirement tracing is usually done in sensitive projects. Here are hints on how to ensure safe operation. - -OFT never changes any of its input files. Exports and reports are written to STDOUT by default. If you use the `-f` option, OFT will write the output to the specified file instead of STDOUT. In this case, existing exports or reports under that path will be overwritten. - -Without previous user consent: - -- Only use STDOUT -- Don't change any input files - -In safe mode, you can still analyze tracing problems with the help of OFT and explain them to the user. - -#### Brave Mode - -If the user accepts, you can modify input files. This mode is intended for advanced users who understand the risks and have taken the necessary precautions. This allows you to fix tracing problems autonomously. Always ask for user consent before making any changes. - -#### Path Discovery - -While projects often adopt typical layouts with directories like `/doc` or `/src`, this depends on the programming language and preferences of the project author. Scan and understand the directory structure before the first trace. - -Directory scans in OFT are recursive. So if you have OFT check the `/doc` directory, it will also scan all subdirectories. - -#### Running a Trace - -Successful execution of OFT results in an exit code of `0`. If any issues are encountered, OFT will return a non-zero exit code. This can be used to determine if the trace was successful or if there were any errors. - -**Basic Trace:** -```bash -oft trace doc/ src/ -``` - -Note that the directories in this example are placeholders and should be replaced with actual paths relevant to the project. - -**Trace with HTML Report:** -```bash -oft trace -o html -f target/report.html doc/ src/ -``` - -**Verbosity Levels:** -- `--v failure_details` (default): Shows only what is broken. -- `--v all`: Shows all items, including successful ones. -- `--v summary`: Shows only the summary statistics. - -For regular tracing the default verbosity is enough. - -#### Step-wise Selective Tracing - -Use artifact type filtering (`-a` to include only specific types, `-i` to ignore others) to focus on specific layers of the tracing chain. - -**Step 1: Design to User Requirements (High-Level)** -Check if features and user requirements are covered by design/architecture. Ignore implementation and tests to get a clean high-level report. -```bash -oft trace -a feat,req,arch,dsn -i impl,utest,itest,stest <input-paths> -``` - -Adapt the artifact types depending on what the project actually uses. - -**Step 2: Implementation and Test to Design (Low-Level)** -Check if design requirements are covered by implementation and tests. Ignore high-level features/requirements if you only want to focus on technical coverage. -```bash -oft trace -a dsn,impl,utest,itest,stest <input-paths> -``` - -Adapt the artifact types depending on what the project actually uses. Remember, each artifact type used in a specification item, automatically exists. There is no declaration required. - -**Step 3: Component-Specific Trace (via Tags)** -Trace only items belonging to a specific tag/component. -```bash -oft trace -t ComponentName <input-paths> -``` -To include untagged items as well (e.g., general requirements): `-t _,ComponentName`. - -#### Understanding the Report - -OFT produces a summary for each specification item. - -**Successful Item Example:** -`ok [ in: 2 / 2 ✔ | out: 1 / 1 ✔ ] dsn~my-dsn~1 (impl, utest)` -- `in: 2 / 2 ✔`: This item has 2 incoming links (coverage), and all are OK. -- `out: 1 / 1 ✔`: This item has 1 outgoing link (covers another item), and it is OK. -- `(impl, utest)`: This item requires coverage in `impl` and `utest`. Since it is `ok`, it has both. - -**Failed Item Example:** -`not ok [ in: 0 / 1 ❌ | out: 0 / 1 ❌ ] dsn~my-dsn~1 (-impl, utest)` -- `0 / 1 ❌`: There is a problem with the links. -- `-impl`: The required `impl` coverage is missing. -- `+impl`: `impl` was covered even though coverage by this artifact type is not required. -- `utest`: The required `utest` coverage is present. - -### Fixing the Reported Tracing Errors - -Tracing errors in OFT are transitive. If a tracing link is broken, it will propagate to all downstream items, causing them to also appear as failed. This ensures that all dependencies are checked for completeness. That means a single broken link can lead to multiple specification items being marked as not covered correctly. - -Here are strategies to detect and resolve tracing errors: - -1. Always check for spelling errors in IDs first. This is the most common cause of broken links. -2. Check if the correct artifact type is being traced in a link. OFT will indicate missing artifact coverage with a minus sign in front of the artifact type. A plus sign indicates coverage by an unexpected artifact type. -3. If coverage exists but covers the wrong revision of a specification item, OFT reports a link as outdated or predated. Ask the user, if they forgot to update the requirement itself or the revision number. In most cases it will be the former. -4. Duplicate specification item IDs mean that coverage cannot be safely determined. Check for copy and paste errors which are the most common cause of duplicate IDs. If you can, try to discern which requirement ID is the correct one. Suggest a correction for the duplicate where possible. -5. If coverage is not recognized, even though it is present in a file, check the [user guide](#user-guide) to see if the file extension is supported. Inform the user if coverage appears in an unsupported file type. -6. Make sure that files and directories that contain example specification items are excluded from coverage checks. OFT uses a positive list of files and directories, so not listing them will exclude them from coverage checks. -7. Complex projects exchange specification files. When a trace is incomplete, check if the upstream specification documents were included. -8. If there are a lot of errors in a report, help the user reduce them gradually. Fix trivial errors like typos that you detect automatically. If you are unsure, ask the user for clarification. -9. For transitive errors use an iterative approach. Fix them from specific to general, starting at the lowest level where the failure occurs. Often fixing the lowest level error will resolve the complete transitive error. -10. Since you do not have to declare artifact types in OFT, a typo in an artifact type will create a new artifact type. If artifact types are not covered, check if they are seldom used. This might be a sign of a typo. In such a case inform the user. -11. If a suffix is not supported by OFT, you cannot import it. Ask the user to create a feature request for the missing suffix in the tracker of the OFT project. -12. Rerun the trace to verify all issues are resolved. - -#### Reference Documentation - -##### User Guide - -For more detailed information, consult the OpenFastTrace User Guide at the following stable GitHub URL: -[https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md) - -##### Project Home on GitHub - -The OFT project can be found under: -[https://github.com/itsallcode/openfasttrace](https://github.com/itsallcode/openfasttrace) - -#### Architecture Template - -An architecture template that uses an arc42 style is available at: -https://github.com/itsallcode/openfasttrace-architecture-template \ No newline at end of file