From e9c385a85e61307b7fd5965de7f8978a5cde2a30 Mon Sep 17 00:00:00 2001 From: muhab Date: Wed, 19 Nov 2025 17:17:09 +0100 Subject: [PATCH 1/2] chore(docs): add requirements mds for existing and to be implemented functionalities --- docs/requirements/AGENT.md | 26 +++ docs/requirements/AllRequirements.md | 149 ++++++++++++++ docs/requirements/SHR-TSSDK-1.md | 13 ++ docs/requirements/SHR-TSSDK-2.md | 13 ++ docs/requirements/SHR-TSSDK-3.md | 13 ++ docs/requirements/SHR-TSSDK-4.md | 13 ++ docs/requirements/SHR-TSSDK-5.md | 13 ++ docs/requirements/SHR-TSSDK-6.md | 13 ++ docs/requirements/SWR-TSSDK-1-1.md | 12 ++ docs/requirements/SWR-TSSDK-1-2.md | 13 ++ docs/requirements/SWR-TSSDK-1-3.md | 13 ++ docs/requirements/SWR-TSSDK-1-4.md | 12 ++ docs/requirements/SWR-TSSDK-1-5.md | 13 ++ docs/requirements/SWR-TSSDK-1-6.md | 13 ++ docs/requirements/SWR-TSSDK-1-7.md | 13 ++ docs/requirements/SWR-TSSDK-2-1.md | 13 ++ docs/requirements/SWR-TSSDK-2-2.md | 13 ++ docs/requirements/SWR-TSSDK-2-3.md | 13 ++ docs/requirements/SWR-TSSDK-2-4.md | 13 ++ docs/requirements/SWR-TSSDK-3-1.md | 13 ++ docs/requirements/SWR-TSSDK-3-2.md | 13 ++ docs/requirements/SWR-TSSDK-3-3.md | 13 ++ docs/requirements/SWR-TSSDK-4-1.md | 13 ++ docs/requirements/SWR-TSSDK-4-2.md | 13 ++ docs/requirements/SWR-TSSDK-4-3.md | 13 ++ docs/requirements/SWR-TSSDK-4-4.md | 14 ++ docs/requirements/SWR-TSSDK-4-5.md | 14 ++ docs/requirements/SWR-TSSDK-5-1.md | 13 ++ docs/requirements/SWR-TSSDK-5-2.md | 13 ++ docs/requirements/SWR-TSSDK-5-3.md | 13 ++ docs/requirements/SWR-TSSDK-6-1.md | 13 ++ docs/requirements/SWR-TSSDK-6-2.md | 13 ++ docs/requirements/SWR-TSSDK-6-3.md | 13 ++ docs/requirements/SWR-TSSDK-6-4.md | 13 ++ docs/requirements/TEMPLATE_SHR.md | 154 +++++++++++++++ docs/requirements/TEMPLATE_SWR.md | 286 +++++++++++++++++++++++++++ 36 files changed, 1031 insertions(+) create mode 100644 docs/requirements/AGENT.md create mode 100644 docs/requirements/AllRequirements.md create mode 100644 docs/requirements/SHR-TSSDK-1.md create mode 100644 docs/requirements/SHR-TSSDK-2.md create mode 100644 docs/requirements/SHR-TSSDK-3.md create mode 100644 docs/requirements/SHR-TSSDK-4.md create mode 100644 docs/requirements/SHR-TSSDK-5.md create mode 100644 docs/requirements/SHR-TSSDK-6.md create mode 100644 docs/requirements/SWR-TSSDK-1-1.md create mode 100644 docs/requirements/SWR-TSSDK-1-2.md create mode 100644 docs/requirements/SWR-TSSDK-1-3.md create mode 100644 docs/requirements/SWR-TSSDK-1-4.md create mode 100644 docs/requirements/SWR-TSSDK-1-5.md create mode 100644 docs/requirements/SWR-TSSDK-1-6.md create mode 100644 docs/requirements/SWR-TSSDK-1-7.md create mode 100644 docs/requirements/SWR-TSSDK-2-1.md create mode 100644 docs/requirements/SWR-TSSDK-2-2.md create mode 100644 docs/requirements/SWR-TSSDK-2-3.md create mode 100644 docs/requirements/SWR-TSSDK-2-4.md create mode 100644 docs/requirements/SWR-TSSDK-3-1.md create mode 100644 docs/requirements/SWR-TSSDK-3-2.md create mode 100644 docs/requirements/SWR-TSSDK-3-3.md create mode 100644 docs/requirements/SWR-TSSDK-4-1.md create mode 100644 docs/requirements/SWR-TSSDK-4-2.md create mode 100644 docs/requirements/SWR-TSSDK-4-3.md create mode 100644 docs/requirements/SWR-TSSDK-4-4.md create mode 100644 docs/requirements/SWR-TSSDK-4-5.md create mode 100644 docs/requirements/SWR-TSSDK-5-1.md create mode 100644 docs/requirements/SWR-TSSDK-5-2.md create mode 100644 docs/requirements/SWR-TSSDK-5-3.md create mode 100644 docs/requirements/SWR-TSSDK-6-1.md create mode 100644 docs/requirements/SWR-TSSDK-6-2.md create mode 100644 docs/requirements/SWR-TSSDK-6-3.md create mode 100644 docs/requirements/SWR-TSSDK-6-4.md create mode 100644 docs/requirements/TEMPLATE_SHR.md create mode 100644 docs/requirements/TEMPLATE_SWR.md diff --git a/docs/requirements/AGENT.md b/docs/requirements/AGENT.md new file mode 100644 index 0000000..6172754 --- /dev/null +++ b/docs/requirements/AGENT.md @@ -0,0 +1,26 @@ +# Requirements Documentation Instructions + +When creating or editing requirement documents: + +1. **Use the template** at `docs/requirements/SWR-TEMPLATE.md` + +2. **Set Requirement Type** using this mapping: + +| Requirement Type | Value | +| ----------------------------- | --------------------------------------- | +| USE_CASE | Software requirement (regulatory) | +| TECHNICAL | Stakeholder requirement (system) | +| FUNCTIONAL | Software requirement (user) | +| INTERFACES | Stakeholder requirement (performance) | +| REGULATORY | Software requirement (system) | +| ENVIRONMENT | Stakeholder requirement (user) | +| SOFTWARE_IO | Software requirement (performance) | +| DOCUMENTATION | Stakeholder requirement (science) | +| FAULT_HANDLING | Stakeholder requirement (business) | +| SOFTWARE_SYSTEM | Stakeholder requirement (cybersecurity) | +| USER_MAINTENANCE | Software requirement (other) | +| DATA_AND_DATABASES | Software requirement (cybersecurity) | +| EXTERNAL_INTERFACES | Stakeholder requirement (regulatory) | +| ACCOMPANYING_DOCUMENTS | Software requirement (business) | +| USER_INTERFACE_SPECIFICATION | Software requirement (user interface) | +| ESSENTIAL_FUNCTION_PROTECTION | Software requirement (science) | \ No newline at end of file diff --git a/docs/requirements/AllRequirements.md b/docs/requirements/AllRequirements.md new file mode 100644 index 0000000..ce2e06b --- /dev/null +++ b/docs/requirements/AllRequirements.md @@ -0,0 +1,149 @@ +Typescript SDK - Requirements +Author Omid Kokabi +Date Oct 14, 2025 + +Color coding +Black = Requirements that are already implemented +Red = Requirements that are not yet implemented + +Requirements +SHR: TSSDK-1 - Authenticated Platform Access +Requirement Type: Stakeholder requirement (security) +Description: Access to the Aignostics Platform shall require valid user authentication credentials. + +SWR-TSSDK-1.1: Token-Based Authentication +Requirement Type: Software requirement (security) +Description: System shall authenticate API requests using access tokens. + +SWR-TSSDK-1.2: Authentication Validation +Requirement Type: Software requirement (security) +Description: CLI shall reject API requests that do not include a valid access token. + +SWR-TSSDK-1.3: Secure authorisation code authentication +Requirement Type: Software requirement (security) +Description: CLI shall support secure authorization code-based authentication flow with cryptographic protection against authorization code interception attacks. + +SWR-TSSDK-1.4: Custom Token Provider +Requirement Type: Software requirement (security) +Description: SDK shall accept user-provided token functions for obtaining access tokens. + +SWR-TSSDK-1.5: Secure Token Storage +Requirement Type: Software requirement (security) +Description: CLI shall store authentication tokens with protection against unauthorized access. + +SWR-TSSDK-1.6: Automatic Token Refresh +Requirement Type: Software requirement (security) +Description: CLI shall automatically refresh access tokens and retry failed API requests when authentication fails and valid refresh tokens are available + +SWR-TSSDK-1.7: Token Removal +Requirement Type: Software requirement (security) +Description: CLI shall enable users to remove stored authentication tokens. + + +SHR: TSSDK-2 - Application Discovery +Requirement Type: Stakeholder requirement (user) +Description: Users shall be able to discover available AI applications and their versions. + +SWR-TSSDK-2.1: Application List Retrieval +Requirement Type: Software requirement (user) +Description: System shall retrieve all available AI applications accessible to the authenticated user. + +SWR-TSSDK-2.2: Application Details +Requirement Type: Software requirement (user) +Description: System shall provide application identification, description, and regulatory compliance information for each retrieved application. + +SWR-TSSDK-2.3: Version List Retrieval +Requirement Type: Software requirement (user) +Description: System shall retrieve all versions for a specified application. + +SWR-TSSDK-2.4: Version Details +Requirement Type: Software requirement (user) +Description: System shall provide version identification, change history, input requirements, and output specifications for each retrieved version. + + +SHR: TSSDK-3 - Application Execution Access +Requirement Type: Stakeholder requirement (user) +Description: Users shall be able to execute AI applications on slide data to generate analytical insights. + +SWR-TSSDK-3.1: Application Run Creation +Requirement Type: Software requirement (user) +Description: System shall create application runs with specified application version, input items, and item- and run metadata and return a unique run identifier upon successful creation. + +SWR-TSSDK-3.2: Input Artifact Specification +Requirement Type: Software requirement (user) +Description: System shall accept input artifacts containing artifact name, download URL, and metadata for each item in the run request. + +SWR-TSSDK-3.3: Request Validation +Requirement Type: Software requirement (user) +Description: System shall validate run request format before submission to the platform. + +SHR: TSSDK-4 - Application Run Management +Requirement Type: Stakeholder requirement (user) +Description: Users shall be able to monitor status and manage the lifecycle of their AI application runs. + +SWR-TSSDK-4.1: List Application Runs +Requirement Type: Software requirement (user) +Description: System shall retrieve a list of application runs with optional filtering by application ID and application version. + +SWR-TSSDK-4.2: Retrieve Run Details +Requirement Type: Software requirement (user) +Description: System shall retrieve detailed information for a specific application run by run ID. + +SWR-TSSDK-4.3: Cancel Application Run +Requirement Type: Software requirement (user) +Description: System shall enable users to cancel a running or queued application run by run ID. + +SWR-TSSDK-4.4: Run Due Date Specification +Requirement Type: Software requirement (user) +Description: System shall accept optional due date timestamp when creating application runs to specify the expected completion time. + +SWR-TSSDK-4.5:Run Deadline Specification +Requirement Type: Software requirement (user) +Description: System shall accept optional deadline timestamp when creating application runs to specify when the +Platform API should automatically cancel the run if not completed. +SHR: TSSDK-5 - Application Results Access +Requirement Type: Stakeholder requirement (user) +Description: Users shall be able to access and retrieve results generated from AI application runs. + +SWR-TSSDK-5.1: Retrieve run items +Requirement Type: Software requirement (user) +Description: System shall retrieve items and their associated output artifacts for a specified application run by run ID. + +SWR-TSSDK-5.2: Item status information +Requirement Type: Software requirement (user) +Description: System shall provide execution state, output availability, termination status, and error details for each item. + +SWR-TSSDK-5.3: Artifact status information +Requirement Type: Software requirement (user) +Description: System shall provide execution state, download availability, termination status, and error details for each output artifact. + + +SHR: TSSDK-6 - Error Communication +Requirement Type: Stakeholder requirement (user) +Description: Users shall receive clear information when operations fail. + +SWR-TSSDK-6.1: Error Classification +Requirement Type: Software requirement (user) +Description: System shall assign a unique error code to each error to enable programmatic error handling and differentiation between error types. + +SWR-TSSDK-6.2: Error Messages +Requirement Type: Software requirement (user) +Description: System shall provide error messages that describe the failure cause and corrective action where applicable. + +SWR-TSSDK-6.3: Error Diagnostic Context +Requirement Type: Software requirement (user) +Description: System shall include diagnostic context in errors including protocol-specific status information for API failures and original error details for debugging. + +SWR-TSSDK-6.4: CLI Error Output +Requirement Type: Software requirement (user) +Description: CLI shall write error messages to standard error stream and provide machine-readable operation status through standard exit mechanisms. + + + + + + + + + + diff --git a/docs/requirements/SHR-TSSDK-1.md b/docs/requirements/SHR-TSSDK-1.md new file mode 100644 index 0000000..9ff0f4e --- /dev/null +++ b/docs/requirements/SHR-TSSDK-1.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-TSSDK-1 +itemTitle: Authenticated Platform Access +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: SECURITY +--- + + + +## Description + +Access to the Aignostics Platform shall require valid user authentication credentials. diff --git a/docs/requirements/SHR-TSSDK-2.md b/docs/requirements/SHR-TSSDK-2.md new file mode 100644 index 0000000..3d58bdc --- /dev/null +++ b/docs/requirements/SHR-TSSDK-2.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-TSSDK-2 +itemTitle: Application Discovery +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to discover available AI applications and their versions. diff --git a/docs/requirements/SHR-TSSDK-3.md b/docs/requirements/SHR-TSSDK-3.md new file mode 100644 index 0000000..fbaadd1 --- /dev/null +++ b/docs/requirements/SHR-TSSDK-3.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-TSSDK-3 +itemTitle: Application Execution Access +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to execute AI applications on slide data to generate analytical insights. diff --git a/docs/requirements/SHR-TSSDK-4.md b/docs/requirements/SHR-TSSDK-4.md new file mode 100644 index 0000000..fe30f47 --- /dev/null +++ b/docs/requirements/SHR-TSSDK-4.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-TSSDK-4 +itemTitle: Application Run Management +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to monitor status and manage the lifecycle of their AI application runs. diff --git a/docs/requirements/SHR-TSSDK-5.md b/docs/requirements/SHR-TSSDK-5.md new file mode 100644 index 0000000..a0eb8bd --- /dev/null +++ b/docs/requirements/SHR-TSSDK-5.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-TSSDK-5 +itemTitle: Application Results Access +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall be able to access and retrieve results generated from AI application runs. diff --git a/docs/requirements/SHR-TSSDK-6.md b/docs/requirements/SHR-TSSDK-6.md new file mode 100644 index 0000000..dce6e0e --- /dev/null +++ b/docs/requirements/SHR-TSSDK-6.md @@ -0,0 +1,13 @@ +--- +itemId: SHR-TSSDK-6 +itemTitle: Error Communication +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: FUNCTIONAL +--- + + + +## Description + +Users shall receive clear information when operations fail. diff --git a/docs/requirements/SWR-TSSDK-1-1.md b/docs/requirements/SWR-TSSDK-1-1.md new file mode 100644 index 0000000..86c1dc1 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-1-1.md @@ -0,0 +1,12 @@ +--- +itemId: SWR-TSSDK-1-1 +itemTitle: Token-Based Authentication +itemHasParent: SHR-TSSDK-1 +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +--- + + + +System shall authenticate API requests using access tokens. diff --git a/docs/requirements/SWR-TSSDK-1-2.md b/docs/requirements/SWR-TSSDK-1-2.md new file mode 100644 index 0000000..dda23ef --- /dev/null +++ b/docs/requirements/SWR-TSSDK-1-2.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-1-2 +itemTitle: Authentication Validation +itemHasParent: SHR-TSSDK-1 +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall reject API requests that do not include a valid access token. diff --git a/docs/requirements/SWR-TSSDK-1-3.md b/docs/requirements/SWR-TSSDK-1-3.md new file mode 100644 index 0000000..b6bde7b --- /dev/null +++ b/docs/requirements/SWR-TSSDK-1-3.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-1-3 +itemTitle: Secure Authorisation Code Authentication +itemHasParent: SHR-TSSDK-1 +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall support secure authorization code-based authentication flow with cryptographic protection against authorization code interception attacks. diff --git a/docs/requirements/SWR-TSSDK-1-4.md b/docs/requirements/SWR-TSSDK-1-4.md new file mode 100644 index 0000000..d015c72 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-1-4.md @@ -0,0 +1,12 @@ +--- +itemId: SWR-TSSDK-1-4 +itemTitle: Custom Token Provider +itemHasParent: SHR-TSSDK-1 +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +--- + + + +SDK shall accept user-provided token functions for obtaining access tokens. diff --git a/docs/requirements/SWR-TSSDK-1-5.md b/docs/requirements/SWR-TSSDK-1-5.md new file mode 100644 index 0000000..0313905 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-1-5.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-1-5 +itemTitle: Secure Token Storage +itemHasParent: SHR-TSSDK-1 +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall store authentication tokens with protection against unauthorized access. diff --git a/docs/requirements/SWR-TSSDK-1-6.md b/docs/requirements/SWR-TSSDK-1-6.md new file mode 100644 index 0000000..3aa60c6 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-1-6.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-1-6 +itemTitle: Automatic Token Refresh +itemHasParent: SHR-TSSDK-1 +itemType: Requirement +# Software requirement (system) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall automatically refresh access tokens and retry failed API requests when authentication fails and valid refresh tokens are available. diff --git a/docs/requirements/SWR-TSSDK-1-7.md b/docs/requirements/SWR-TSSDK-1-7.md new file mode 100644 index 0000000..3fc0638 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-1-7.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-1-7 +itemTitle: Token Removal +itemHasParent: SHR-TSSDK-1 +itemType: Requirement +# Software requirement (user) +Requirement type: SECURITY +Layer: CLI +--- + + + +CLI shall enable users to remove stored authentication tokens. diff --git a/docs/requirements/SWR-TSSDK-2-1.md b/docs/requirements/SWR-TSSDK-2-1.md new file mode 100644 index 0000000..d3abe65 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-2-1.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-2-1 +itemTitle: Application List Retrieval +itemHasParent: SHR-TSSDK-2 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve all available AI applications accessible to the authenticated user. diff --git a/docs/requirements/SWR-TSSDK-2-2.md b/docs/requirements/SWR-TSSDK-2-2.md new file mode 100644 index 0000000..db59f0f --- /dev/null +++ b/docs/requirements/SWR-TSSDK-2-2.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-2-2 +itemTitle: Application Details +itemHasParent: SHR-TSSDK-2 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide application identification, description, and regulatory compliance information for each retrieved application. diff --git a/docs/requirements/SWR-TSSDK-2-3.md b/docs/requirements/SWR-TSSDK-2-3.md new file mode 100644 index 0000000..726d4e4 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-2-3.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-2-3 +itemTitle: Version List Retrieval +itemHasParent: SHR-TSSDK-2 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve all versions for a specified application. diff --git a/docs/requirements/SWR-TSSDK-2-4.md b/docs/requirements/SWR-TSSDK-2-4.md new file mode 100644 index 0000000..8f7f233 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-2-4.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-2-4 +itemTitle: Version Details +itemHasParent: SHR-TSSDK-2 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide version identification, change history, input requirements, and output specifications for each retrieved version. diff --git a/docs/requirements/SWR-TSSDK-3-1.md b/docs/requirements/SWR-TSSDK-3-1.md new file mode 100644 index 0000000..5a159b7 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-3-1.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-3-1 +itemTitle: Application Run Creation +itemHasParent: SHR-TSSDK-3 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall create application runs with specified application version, input items, and item- and run metadata and return a unique run identifier upon successful creation. diff --git a/docs/requirements/SWR-TSSDK-3-2.md b/docs/requirements/SWR-TSSDK-3-2.md new file mode 100644 index 0000000..8c3c61a --- /dev/null +++ b/docs/requirements/SWR-TSSDK-3-2.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-3-2 +itemTitle: Input Artifact Specification +itemHasParent: SHR-TSSDK-3 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall accept input artifacts containing artifact name, download URL, and metadata for each item in the run request. diff --git a/docs/requirements/SWR-TSSDK-3-3.md b/docs/requirements/SWR-TSSDK-3-3.md new file mode 100644 index 0000000..3aab995 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-3-3.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-3-3 +itemTitle: Request Validation +itemHasParent: SHR-TSSDK-3 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall validate run request format before submission to the platform. diff --git a/docs/requirements/SWR-TSSDK-4-1.md b/docs/requirements/SWR-TSSDK-4-1.md new file mode 100644 index 0000000..837217e --- /dev/null +++ b/docs/requirements/SWR-TSSDK-4-1.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-4-1 +itemTitle: List Application Runs +itemHasParent: SHR-TSSDK-4 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve a list of application runs with optional filtering by application ID and application version. diff --git a/docs/requirements/SWR-TSSDK-4-2.md b/docs/requirements/SWR-TSSDK-4-2.md new file mode 100644 index 0000000..64191a5 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-4-2.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-4-2 +itemTitle: Retrieve Run Details +itemHasParent: SHR-TSSDK-4 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve detailed information for a specific application run by run ID. diff --git a/docs/requirements/SWR-TSSDK-4-3.md b/docs/requirements/SWR-TSSDK-4-3.md new file mode 100644 index 0000000..f3e9bd4 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-4-3.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-4-3 +itemTitle: Cancel Application Run +itemHasParent: SHR-TSSDK-4 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall enable users to cancel a running or queued application run by run ID. diff --git a/docs/requirements/SWR-TSSDK-4-4.md b/docs/requirements/SWR-TSSDK-4-4.md new file mode 100644 index 0000000..67e5933 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-4-4.md @@ -0,0 +1,14 @@ +--- +itemId: SWR-TSSDK-4-4 +itemTitle: Run Due Date Specification +itemHasParent: SHR-TSSDK-4 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + + +System shall accept optional due date timestamp when creating application runs to specify the expected completion time. diff --git a/docs/requirements/SWR-TSSDK-4-5.md b/docs/requirements/SWR-TSSDK-4-5.md new file mode 100644 index 0000000..9eda3e3 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-4-5.md @@ -0,0 +1,14 @@ +--- +itemId: SWR-TSSDK-4-5 +itemTitle: Run Deadline Specification +itemHasParent: SHR-TSSDK-4 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + + +System shall accept optional deadline timestamp when creating application runs to specify when the Platform API should automatically cancel the run if not completed. diff --git a/docs/requirements/SWR-TSSDK-5-1.md b/docs/requirements/SWR-TSSDK-5-1.md new file mode 100644 index 0000000..eee246b --- /dev/null +++ b/docs/requirements/SWR-TSSDK-5-1.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-5-1 +itemTitle: Retrieve Run Items +itemHasParent: SHR-TSSDK-5 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall retrieve items and their associated output artifacts for a specified application run by run ID. diff --git a/docs/requirements/SWR-TSSDK-5-2.md b/docs/requirements/SWR-TSSDK-5-2.md new file mode 100644 index 0000000..a51046d --- /dev/null +++ b/docs/requirements/SWR-TSSDK-5-2.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-5-2 +itemTitle: Item Status Information +itemHasParent: SHR-TSSDK-5 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide execution state, output availability, termination status, and error details for each item. diff --git a/docs/requirements/SWR-TSSDK-5-3.md b/docs/requirements/SWR-TSSDK-5-3.md new file mode 100644 index 0000000..fb18410 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-5-3.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-5-3 +itemTitle: Artifact Status Information +itemHasParent: SHR-TSSDK-5 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide execution state, download availability, termination status, and error details for each output artifact. diff --git a/docs/requirements/SWR-TSSDK-6-1.md b/docs/requirements/SWR-TSSDK-6-1.md new file mode 100644 index 0000000..e209146 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-6-1.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-6-1 +itemTitle: Error Classification +itemHasParent: SHR-TSSDK-6 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall assign a unique error code to each error to enable programmatic error handling and differentiation between error types. diff --git a/docs/requirements/SWR-TSSDK-6-2.md b/docs/requirements/SWR-TSSDK-6-2.md new file mode 100644 index 0000000..e9f38dc --- /dev/null +++ b/docs/requirements/SWR-TSSDK-6-2.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-6-2 +itemTitle: Error Messages +itemHasParent: SHR-TSSDK-6 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall provide error messages that describe the failure cause and corrective action where applicable. diff --git a/docs/requirements/SWR-TSSDK-6-3.md b/docs/requirements/SWR-TSSDK-6-3.md new file mode 100644 index 0000000..154462e --- /dev/null +++ b/docs/requirements/SWR-TSSDK-6-3.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-6-3 +itemTitle: Error Diagnostic Context +itemHasParent: SHR-TSSDK-6 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + + + +System shall include diagnostic context in errors including protocol-specific status information for API failures and original error details for debugging. diff --git a/docs/requirements/SWR-TSSDK-6-4.md b/docs/requirements/SWR-TSSDK-6-4.md new file mode 100644 index 0000000..d6667f5 --- /dev/null +++ b/docs/requirements/SWR-TSSDK-6-4.md @@ -0,0 +1,13 @@ +--- +itemId: SWR-TSSDK-6-4 +itemTitle: CLI Error Output +itemHasParent: SHR-TSSDK-6 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: CLI +--- + + + +CLI shall write error messages to standard error stream and provide machine-readable operation status through standard exit mechanisms. diff --git a/docs/requirements/TEMPLATE_SHR.md b/docs/requirements/TEMPLATE_SHR.md new file mode 100644 index 0000000..385d33e --- /dev/null +++ b/docs/requirements/TEMPLATE_SHR.md @@ -0,0 +1,154 @@ +# SHR Template - Stakeholder Health Requirement + +**Purpose**: Use this template to create Stakeholder Requirements (SHR) - high-level requirements that describe what stakeholders need from the system. + +## Template Structure + +```markdown +--- +itemId: SHR-[MODULE]-[NUMBER] +itemTitle: [Brief Descriptive Title] +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: [ENVIRONMENT|FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABILITY] +--- + +## Description + +[Detailed description of the stakeholder requirement. This should clearly state what users/stakeholders need to be able to do or what the system needs to provide. Write in complete sentences describing the capability or need from the stakeholder's perspective.] +``` + +## Field Definitions + +### YAML Frontmatter (Required) + +- **itemId**: Unique identifier following pattern `SHR-[MODULE]-[NUMBER]` + - `[MODULE]`: The system module or domain (e.g., APPLICATION, SYSTEM, BUCKET, DATASET, VISUALIZATION) + - `[NUMBER]`: Sequential number starting from 1 for each module + - Example: `SHR-APPLICATION-1`, `SHR-SYSTEM-2` + +- **itemTitle**: Short, descriptive title (3-8 words recommended) + - Should be clear and specific + - Use title case + - Example: "Application Run Management", "System Health Monitoring and Observability" + +- **itemType**: Always set to `Requirement` for requirements documents + +- **Requirement type**: Choose one based on the nature of the requirement: + - `ENVIRONMENT`: Requirements about the operating context, user workflows, or system environment + - `FUNCTIONAL`: Requirements describing specific system functions or capabilities + - `REGULATORY`: Requirements derived from regulations, standards, or compliance needs + - `PERFORMANCE`: Requirements about system performance, speed, or efficiency + - `SECURITY`: Requirements about system security, access control, or data protection + - `USABILITY`: Requirements about user experience, accessibility, or ease of use + +### Description Section (Required) + +- **Format**: Markdown heading level 2 (`## Description`) +- **Content**: 1-3 paragraphs describing the stakeholder requirement +- **Style**: + - Write from stakeholder/user perspective + - Use "Users shall be able to..." or "The system shall provide..." + - Be clear and specific about the capability or need + - Focus on WHAT is needed, not HOW it will be implemented + - Avoid technical implementation details + +## Examples + +### Example 1: User-Facing Capability +```markdown +--- +itemId: SHR-APPLICATION-1 +itemTitle: Application Discovery and Navigation +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: ENVIRONMENT +--- + +## Description + +Users shall be able to view available AI applications and navigate to specific application views to access application functionality. +``` + +### Example 2: System Capability with Detail +```markdown +--- +itemId: SHR-SYSTEM-1 +itemTitle: System Health Monitoring and Observability +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: ENVIRONMENT +--- + +## Description + +Users shall be able to monitor the operational health and status of the system through multiple interfaces to ensure system reliability, diagnose issues, and maintain confidence in system availability. The system shall provide transparent, real-time visibility into its operational state across all user interaction points. +``` + +### Example 3: Workflow Requirement +```markdown +--- +itemId: SHR-APPLICATION-2 +itemTitle: Application Run Management +itemType: Requirement +# Stakeholder requirement (user) +Requirement type: ENVIRONMENT +--- + +## Description + +Users shall be able to execute AI applications on their data by preparing data, submitting runs, monitoring run status, managing run lifecycle including cancellation, and accessing results. +``` + +## Naming Conventions + +### Module Names +Use clear, consistent module names that reflect your system architecture: +- APPLICATION (for application management features) +- SYSTEM (for system-wide capabilities) +- BUCKET (for storage management) +- DATASET (for data operations) +- VISUALIZATION (for visualization tools) +- USER (for user management) +- AUTH (for authentication/authorization) +- API (for API-specific requirements) +- etc. + +### Numbering +- Start from 1 for each module +- Increment sequentially (1, 2, 3, ...) +- Use the same number space across all requirement types for the module +- Example: SHR-APPLICATION-1, SHR-APPLICATION-2, SHR-APPLICATION-3 + +## Best Practices + +1. **Keep it High-Level**: SHRs describe stakeholder needs, not technical solutions +2. **User-Centric**: Write from the perspective of what users need to accomplish +3. **Complete**: Each SHR should be a complete, standalone capability description +4. **Verifiable**: Write requirements that can be verified through testing or demonstration +5. **Clear Scope**: Define the boundaries of what the requirement covers +6. **Parent-Child**: SHRs will have child SWR requirements that detail HOW to implement them + +## Validation Checklist + +Before finalizing an SHR, verify: +- [ ] itemId follows SHR-[MODULE]-[NUMBER] pattern +- [ ] itemTitle is clear and descriptive +- [ ] itemType is set to "Requirement" +- [ ] Requirement type is one of the valid values +- [ ] Description section exists with ## heading +- [ ] Description explains WHAT stakeholders need (not HOW) +- [ ] Language is clear and unambiguous +- [ ] Requirement is testable/verifiable +- [ ] YAML frontmatter is properly formatted + +## Notes for AI Agents + +When generating SHR files: +1. Read the project documentation to understand modules and architecture +2. Identify high-level stakeholder needs and capabilities +3. Group related requirements under appropriate modules +4. Create one SHR file per stakeholder requirement +5. Ensure each SHR can be decomposed into multiple SWR requirements +6. Use consistent terminology throughout all requirements +7. Consider the user journey and workflows when defining requirements diff --git a/docs/requirements/TEMPLATE_SWR.md b/docs/requirements/TEMPLATE_SWR.md new file mode 100644 index 0000000..7014ad3 --- /dev/null +++ b/docs/requirements/TEMPLATE_SWR.md @@ -0,0 +1,286 @@ +# SWR Template - Software Requirement + +**Purpose**: Use this template to create Software Requirements (SWR) - detailed technical requirements that implement stakeholder requirements (SHR). + +## Template Structure + +```markdown +--- +itemId: SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME] +itemTitle: [Brief Descriptive Title] +itemHasParent: SHR-[MODULE]-[PARENT_NUMBER] +itemType: Requirement +# Software requirement (user|system) +Requirement type: [FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABILITY] +Layer: [System (backend logic)|User Interface (frontend)|GUI|CLI|API|Database|etc.] +--- + +[Detailed requirement description. Can be written as a plain statement or as a user story. Should clearly specify the technical implementation requirement.] +``` + +## Field Definitions + +### YAML Frontmatter (Required) + +- **itemId**: Unique identifier following pattern `SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME]` + - `[MODULE]`: Same module as parent SHR (e.g., APPLICATION, SYSTEM, BUCKET) + - `[PARENT_NUMBER]`: The number from the parent SHR (e.g., if parent is SHR-APPLICATION-2, use 2) + - `[DESCRIPTIVE_NAME]`: Short descriptive name or sequential number (e.g., LIST-APPS, 1, 2) + - Example: `SWR-APPLICATION-1-LIST`, `SWR-APPLICATION-2-1`, `SWR-SYSTEM-1-GUI-HEALTH` + +- **itemTitle**: Short, descriptive title (3-8 words recommended) + - Should be specific about the technical requirement + - Use title case + - Example: "List Available Applications", "Accept Optional Run Name and Description" + +- **itemHasParent**: Reference to parent SHR using format `SHR-[MODULE]-[NUMBER]` + - Must match an existing SHR itemId + - Example: `SHR-APPLICATION-1`, `SHR-SYSTEM-2` + +- **itemType**: Always set to `Requirement` for requirements documents + +- **Software requirement comment**: Choose one: + - `# Software requirement (user)` - User-facing software requirements + - `# Software requirement (system)` - System-level software requirements + +- **Requirement type**: Choose one based on the nature of the requirement: + - `FUNCTIONAL`: Requirements describing specific system functions or operations + - `REGULATORY`: Requirements derived from regulations, standards, or compliance needs + - `PERFORMANCE`: Requirements about system performance, speed, or efficiency + - `SECURITY`: Requirements about system security, access control, or data protection + - `USABILITY`: Requirements about user experience, accessibility, or ease of use + +- **Layer**: (Optional) Specify the architectural layer: + - `System (backend logic)` - Backend business logic, services, APIs + - `User Interface (frontend)` - Frontend web/mobile interface + - `GUI` - Desktop GUI application + - `CLI` - Command-line interface + - `API` - API endpoints and contracts + - `Database` - Database schema and operations + - `System (frontend interface)` - Frontend system components + - Or any other layer relevant to your architecture + +### Requirement Description (Required) + +- **Format**: Direct text after YAML frontmatter (no heading) +- **Content**: 1-3 sentences describing the specific technical requirement +- **Style Options**: + + **Option 1 - Plain Statement** (most common): + ``` + System shall provide a list of available applications for user selection. + ``` + + **Option 2 - User Story Format**: + ``` + As a user, I expected the current health of Launchpad being always visible in the footer of the GUI so that I can ensure the system is operational. + ``` + + **Option 3 - Detailed Statement**: + ``` + System shall accept optional user-provided run name and description during application run submission. The system shall validate that run names do not exceed 100 characters and descriptions do not exceed 500 characters when provided, and shall store these metadata fields with the run record. + ``` + +- **Guidelines**: + - Be specific about technical implementation + - Include validation rules, constraints, or limits if applicable + - Use "System shall..." for system actions + - Use "As a user..." for user story format + - Focus on HOW the parent SHR will be implemented + - Include acceptance criteria when relevant + +## Examples + +### Example 1: Simple Backend Requirement +```markdown +--- +itemId: SWR-APPLICATION-1-1 +itemTitle: List Available Applications +itemHasParent: SHR-APPLICATION-1 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + +System shall provide a list of available applications for user selection. +``` + +### Example 2: GUI Requirement with User Story +```markdown +--- +itemId: SWR-SYSTEM-GUI-HEALTH-1 +itemTitle: GUI System Health Visibility +itemHasParent: SHR-SYSTEM-1 +itemType: Requirement +# Software requirement (system) +Requirement type: REGULATORY +Layer: GUI +--- + +As a user, I expected the current health of Launchpad being always visible in the footer of the GUI so that I can ensure the system is operational. +``` + +### Example 3: Detailed Requirement with Validation +```markdown +--- +itemId: SWR-APPLICATION-2-13 +itemTitle: Accept Optional Run Name and Description +itemHasParent: SHR-APPLICATION-2 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + +System shall accept optional user-provided run name and description during application run submission. The system shall validate that run names do not exceed 100 characters and descriptions do not exceed 500 characters when provided, and shall store these metadata fields with the run record. +``` + +### Example 4: Storage Operation Requirement +```markdown +--- +itemId: SWR-BUCKET-1-1 +itemTitle: Upload Directory Structure to Bucket Storage +itemHasParent: SHR-BUCKET-1 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + +System shall upload local directory structures with multiple files and subdirectories to bucket storage while preserving file organization. +``` + +### Example 5: Complex Multi-Granularity Requirement +```markdown +--- +itemId: SWR-APPLICATION-3-1 +itemTitle: Download Application Run Results +itemHasParent: SHR-APPLICATION-3 +itemType: Requirement +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: System (backend logic) +--- + +System shall download application run results at multiple granularity levels: all items per run, individual items, and individual artifacts per item. The system shall download to specified destination directories when requested by run identifier, retrieve results regardless of run status, and provide download confirmation with status information indicating whether run was completed or canceled. +``` + +## Naming Conventions + +### itemId Pattern +`SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME]` + +**Descriptive Name Options**: +1. **Sequential numbers**: 1, 2, 3, etc. + - Example: SWR-APPLICATION-1-1, SWR-APPLICATION-1-2 + - Pro: Simple, easy to generate + - Con: Less self-documenting + +2. **Short descriptive keywords**: LIST, UPLOAD, DELETE, etc. + - Example: SWR-APPLICATION-1-LIST, SWR-BUCKET-1-UPLOAD + - Pro: More readable, self-documenting + - Con: Requires consistent naming + +3. **Combined approach**: Use descriptive names for major features, numbers for variations + - Example: SWR-APPLICATION-2-SUBMIT-1, SWR-APPLICATION-2-SUBMIT-2 + - Pro: Balances clarity and simplicity + - Con: More complex to manage + +**Recommendation**: Use sequential numbers unless descriptive names add significant clarity. + +### Module and Parent Number +- Must match the parent SHR +- Example: If parent is `SHR-APPLICATION-2`, then SWR prefix is `SWR-APPLICATION-2-*` + +## Relationship to SHR + +Each SWR must: +1. Reference exactly one parent SHR via `itemHasParent` +2. Implement a specific aspect of that parent SHR +3. Be more detailed and technical than the parent SHR +4. Focus on HOW to implement WHAT the parent SHR describes + +**Example Breakdown**: +``` +SHR-APPLICATION-1: "Application Discovery and Navigation" +├── SWR-APPLICATION-1-1: "List Available Applications" +├── SWR-APPLICATION-1-2: "Display Application Details" +└── SWR-APPLICATION-1-3: "Navigate to Application View" +``` + +## Layer Guidelines + +Choose the appropriate layer based on where the requirement is implemented: + +- **System (backend logic)**: Business logic, data processing, API services +- **User Interface (frontend)**: Web or mobile UI components and interactions +- **GUI**: Desktop graphical interface +- **CLI**: Command-line interface commands and options +- **API**: REST/GraphQL endpoints, request/response formats +- **Database**: Schema, queries, data persistence +- **Integration**: External system integrations +- **Infrastructure**: Deployment, scaling, monitoring + +**Note**: Layer field is optional but recommended for clarity. Omit if not applicable to your project. + +## Best Practices + +1. **Specificity**: SWRs should be specific enough to implement and test +2. **Traceability**: Always link to parent SHR via itemHasParent +3. **Granularity**: One SWR per distinct technical requirement +4. **Testability**: Write requirements that can be verified through automated or manual testing +5. **Completeness**: Include validation rules, constraints, error handling +6. **Clarity**: Use clear, unambiguous language +7. **Consistency**: Use consistent terminology with parent SHR and other SWRs + +## Common Patterns + +### Validation Requirements +```markdown +System shall validate that [field] does not exceed [limit] characters when provided, and shall [action] when validation fails. +``` + +### Data Operations +```markdown +System shall [action] [data] to/from [location] while [constraint/condition]. +``` + +### User Interface Requirements +```markdown +As a user, I expect [UI element] to [behavior] in [location] so that [benefit/reason]. +``` + +### Multi-Step Operations +```markdown +System shall [action1] at multiple [scope] levels: [option1], [option2], and [option3]. The system shall [action2] when [condition], and provide [output] with [details]. +``` + +## Validation Checklist + +Before finalizing an SWR, verify: +- [ ] itemId follows SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME] pattern +- [ ] itemTitle is clear and descriptive +- [ ] itemHasParent references a valid SHR +- [ ] itemType is set to "Requirement" +- [ ] Software requirement type (user|system) is specified +- [ ] Requirement type is one of the valid values +- [ ] Layer is specified (if applicable) +- [ ] Requirement description is clear and implementable +- [ ] Requirement is testable/verifiable +- [ ] YAML frontmatter is properly formatted +- [ ] Requirement implements part of the parent SHR + +## Notes for AI Agents + +When generating SWR files: +1. Always start by identifying the parent SHR +2. Break down the parent SHR into logical, implementable components +3. Create one SWR file per technical requirement +4. Ensure each SWR is specific enough to implement +5. Include validation rules and constraints where applicable +6. Use consistent terminology with parent SHR +7. Consider the full technical stack (frontend, backend, database, etc.) +8. Group related SWRs under the same parent SHR +9. Ensure completeness: all aspects of parent SHR should be covered by child SWRs +10. Maintain traceability: every SWR should clearly implement part of its parent SHR From 348778387acf0ccb46517129285b78666b9dfc67 Mon Sep 17 00:00:00 2001 From: muhab Date: Wed, 19 Nov 2025 18:42:17 +0100 Subject: [PATCH 2/2] chore(docs): add requirements mds for existing and to be implemented functionalities --- docs/requirements/AGENT.md | 4 +- docs/requirements/AllRequirements.md | 149 ------------------ .../{SHR-TSSDK-2.md => SHR-APP-DISCOVERY.md} | 4 +- .../{SHR-TSSDK-3.md => SHR-APP-EXEC.md} | 4 +- .../{SHR-TSSDK-5.md => SHR-APP-RESULTS.md} | 4 +- .../{SHR-TSSDK-4.md => SHR-APP-RUN-MGMT.md} | 4 +- .../{SHR-TSSDK-1.md => SHR-AUTH.md} | 4 +- .../{SHR-TSSDK-6.md => SHR-ERROR-COMM.md} | 4 +- ...DK-2-2.md => SWR-APP-DISCOVERY-DETAILS.md} | 4 +- ...TSSDK-2-1.md => SWR-APP-DISCOVERY-LIST.md} | 4 +- ...d => SWR-APP-DISCOVERY-VERSION-DETAILS.md} | 4 +- ...3.md => SWR-APP-DISCOVERY-VERSION-LIST.md} | 4 +- ...-3-2.md => SWR-APP-EXEC-INPUT-ARTIFACT.md} | 4 +- ....md => SWR-APP-EXEC-REQUEST-VALIDATION.md} | 4 +- ...DK-3-1.md => SWR-APP-EXEC-RUN-CREATION.md} | 4 +- ....md => SWR-APP-RESULTS-ARTIFACT-STATUS.md} | 4 +- ...-5-2.md => SWR-APP-RESULTS-ITEM-STATUS.md} | 4 +- ...1.md => SWR-APP-RESULTS-RETRIEVE-ITEMS.md} | 4 +- ...SSDK-4-3.md => SWR-APP-RUN-MGMT-CANCEL.md} | 4 +- ...DK-4-5.md => SWR-APP-RUN-MGMT-DEADLINE.md} | 4 +- ...SDK-4-2.md => SWR-APP-RUN-MGMT-DETAILS.md} | 4 +- ...DK-4-4.md => SWR-APP-RUN-MGMT-DUE-DATE.md} | 4 +- ...-TSSDK-4-1.md => SWR-APP-RUN-MGMT-LIST.md} | 4 +- ...-TSSDK-1-6.md => SWR-AUTH-AUTO-REFRESH.md} | 4 +- ...SWR-TSSDK-1-3.md => SWR-AUTH-CODE-FLOW.md} | 4 +- ...SDK-1-4.md => SWR-AUTH-CUSTOM-PROVIDER.md} | 4 +- ...SSDK-1-5.md => SWR-AUTH-SECURE-STORAGE.md} | 4 +- ...R-TSSDK-1-1.md => SWR-AUTH-TOKEN-BASED.md} | 4 +- ...TSSDK-1-7.md => SWR-AUTH-TOKEN-REMOVAL.md} | 4 +- ...WR-TSSDK-1-2.md => SWR-AUTH-VALIDATION.md} | 4 +- ...-1.md => SWR-ERROR-COMM-CLASSIFICATION.md} | 4 +- ...DK-6-4.md => SWR-ERROR-COMM-CLI-OUTPUT.md} | 4 +- ...d => SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md} | 4 +- ...SSDK-6-2.md => SWR-ERROR-COMM-MESSAGES.md} | 4 +- docs/requirements/TEMPLATE_SHR.md | 85 +++++----- docs/requirements/TEMPLATE_SWR.md | 138 ++++++++-------- 36 files changed, 190 insertions(+), 314 deletions(-) delete mode 100644 docs/requirements/AllRequirements.md rename docs/requirements/{SHR-TSSDK-2.md => SHR-APP-DISCOVERY.md} (76%) rename docs/requirements/{SHR-TSSDK-3.md => SHR-APP-EXEC.md} (79%) rename docs/requirements/{SHR-TSSDK-5.md => SHR-APP-RESULTS.md} (78%) rename docs/requirements/{SHR-TSSDK-4.md => SHR-APP-RUN-MGMT.md} (78%) rename docs/requirements/{SHR-TSSDK-1.md => SHR-AUTH.md} (79%) rename docs/requirements/{SHR-TSSDK-6.md => SHR-ERROR-COMM.md} (75%) rename docs/requirements/{SWR-TSSDK-2-2.md => SWR-APP-DISCOVERY-DETAILS.md} (82%) rename docs/requirements/{SWR-TSSDK-2-1.md => SWR-APP-DISCOVERY-LIST.md} (82%) rename docs/requirements/{SWR-TSSDK-2-4.md => SWR-APP-DISCOVERY-VERSION-DETAILS.md} (81%) rename docs/requirements/{SWR-TSSDK-2-3.md => SWR-APP-DISCOVERY-VERSION-LIST.md} (78%) rename docs/requirements/{SWR-TSSDK-3-2.md => SWR-APP-EXEC-INPUT-ARTIFACT.md} (83%) rename docs/requirements/{SWR-TSSDK-3-3.md => SWR-APP-EXEC-REQUEST-VALIDATION.md} (79%) rename docs/requirements/{SWR-TSSDK-3-1.md => SWR-APP-EXEC-RUN-CREATION.md} (85%) rename docs/requirements/{SWR-TSSDK-5-3.md => SWR-APP-RESULTS-ARTIFACT-STATUS.md} (82%) rename docs/requirements/{SWR-TSSDK-5-2.md => SWR-APP-RESULTS-ITEM-STATUS.md} (82%) rename docs/requirements/{SWR-TSSDK-5-1.md => SWR-APP-RESULTS-RETRIEVE-ITEMS.md} (81%) rename docs/requirements/{SWR-TSSDK-4-3.md => SWR-APP-RUN-MGMT-CANCEL.md} (81%) rename docs/requirements/{SWR-TSSDK-4-5.md => SWR-APP-RUN-MGMT-DEADLINE.md} (85%) rename docs/requirements/{SWR-TSSDK-4-2.md => SWR-APP-RUN-MGMT-DETAILS.md} (81%) rename docs/requirements/{SWR-TSSDK-4-4.md => SWR-APP-RUN-MGMT-DUE-DATE.md} (84%) rename docs/requirements/{SWR-TSSDK-4-1.md => SWR-APP-RUN-MGMT-LIST.md} (83%) rename docs/requirements/{SWR-TSSDK-1-6.md => SWR-AUTH-AUTO-REFRESH.md} (85%) rename docs/requirements/{SWR-TSSDK-1-3.md => SWR-AUTH-CODE-FLOW.md} (87%) rename docs/requirements/{SWR-TSSDK-1-4.md => SWR-AUTH-CUSTOM-PROVIDER.md} (81%) rename docs/requirements/{SWR-TSSDK-1-5.md => SWR-AUTH-SECURE-STORAGE.md} (82%) rename docs/requirements/{SWR-TSSDK-1-1.md => SWR-AUTH-TOKEN-BASED.md} (81%) rename docs/requirements/{SWR-TSSDK-1-7.md => SWR-AUTH-TOKEN-REMOVAL.md} (80%) rename docs/requirements/{SWR-TSSDK-1-2.md => SWR-AUTH-VALIDATION.md} (83%) rename docs/requirements/{SWR-TSSDK-6-1.md => SWR-ERROR-COMM-CLASSIFICATION.md} (82%) rename docs/requirements/{SWR-TSSDK-6-4.md => SWR-ERROR-COMM-CLI-OUTPUT.md} (82%) rename docs/requirements/{SWR-TSSDK-6-3.md => SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md} (83%) rename docs/requirements/{SWR-TSSDK-6-2.md => SWR-ERROR-COMM-MESSAGES.md} (82%) diff --git a/docs/requirements/AGENT.md b/docs/requirements/AGENT.md index 6172754..38741c6 100644 --- a/docs/requirements/AGENT.md +++ b/docs/requirements/AGENT.md @@ -2,7 +2,9 @@ When creating or editing requirement documents: -1. **Use the template** at `docs/requirements/SWR-TEMPLATE.md` +1. **Use the template** at `docs/requirements/TEMPLATE_SHR.md` for Stakeholder Requirement + +2. **Use the template** at `docs/requirements/TEMPLATE_SWR.md` for Software Requirements 2. **Set Requirement Type** using this mapping: diff --git a/docs/requirements/AllRequirements.md b/docs/requirements/AllRequirements.md deleted file mode 100644 index ce2e06b..0000000 --- a/docs/requirements/AllRequirements.md +++ /dev/null @@ -1,149 +0,0 @@ -Typescript SDK - Requirements -Author Omid Kokabi -Date Oct 14, 2025 - -Color coding -Black = Requirements that are already implemented -Red = Requirements that are not yet implemented - -Requirements -SHR: TSSDK-1 - Authenticated Platform Access -Requirement Type: Stakeholder requirement (security) -Description: Access to the Aignostics Platform shall require valid user authentication credentials. - -SWR-TSSDK-1.1: Token-Based Authentication -Requirement Type: Software requirement (security) -Description: System shall authenticate API requests using access tokens. - -SWR-TSSDK-1.2: Authentication Validation -Requirement Type: Software requirement (security) -Description: CLI shall reject API requests that do not include a valid access token. - -SWR-TSSDK-1.3: Secure authorisation code authentication -Requirement Type: Software requirement (security) -Description: CLI shall support secure authorization code-based authentication flow with cryptographic protection against authorization code interception attacks. - -SWR-TSSDK-1.4: Custom Token Provider -Requirement Type: Software requirement (security) -Description: SDK shall accept user-provided token functions for obtaining access tokens. - -SWR-TSSDK-1.5: Secure Token Storage -Requirement Type: Software requirement (security) -Description: CLI shall store authentication tokens with protection against unauthorized access. - -SWR-TSSDK-1.6: Automatic Token Refresh -Requirement Type: Software requirement (security) -Description: CLI shall automatically refresh access tokens and retry failed API requests when authentication fails and valid refresh tokens are available - -SWR-TSSDK-1.7: Token Removal -Requirement Type: Software requirement (security) -Description: CLI shall enable users to remove stored authentication tokens. - - -SHR: TSSDK-2 - Application Discovery -Requirement Type: Stakeholder requirement (user) -Description: Users shall be able to discover available AI applications and their versions. - -SWR-TSSDK-2.1: Application List Retrieval -Requirement Type: Software requirement (user) -Description: System shall retrieve all available AI applications accessible to the authenticated user. - -SWR-TSSDK-2.2: Application Details -Requirement Type: Software requirement (user) -Description: System shall provide application identification, description, and regulatory compliance information for each retrieved application. - -SWR-TSSDK-2.3: Version List Retrieval -Requirement Type: Software requirement (user) -Description: System shall retrieve all versions for a specified application. - -SWR-TSSDK-2.4: Version Details -Requirement Type: Software requirement (user) -Description: System shall provide version identification, change history, input requirements, and output specifications for each retrieved version. - - -SHR: TSSDK-3 - Application Execution Access -Requirement Type: Stakeholder requirement (user) -Description: Users shall be able to execute AI applications on slide data to generate analytical insights. - -SWR-TSSDK-3.1: Application Run Creation -Requirement Type: Software requirement (user) -Description: System shall create application runs with specified application version, input items, and item- and run metadata and return a unique run identifier upon successful creation. - -SWR-TSSDK-3.2: Input Artifact Specification -Requirement Type: Software requirement (user) -Description: System shall accept input artifacts containing artifact name, download URL, and metadata for each item in the run request. - -SWR-TSSDK-3.3: Request Validation -Requirement Type: Software requirement (user) -Description: System shall validate run request format before submission to the platform. - -SHR: TSSDK-4 - Application Run Management -Requirement Type: Stakeholder requirement (user) -Description: Users shall be able to monitor status and manage the lifecycle of their AI application runs. - -SWR-TSSDK-4.1: List Application Runs -Requirement Type: Software requirement (user) -Description: System shall retrieve a list of application runs with optional filtering by application ID and application version. - -SWR-TSSDK-4.2: Retrieve Run Details -Requirement Type: Software requirement (user) -Description: System shall retrieve detailed information for a specific application run by run ID. - -SWR-TSSDK-4.3: Cancel Application Run -Requirement Type: Software requirement (user) -Description: System shall enable users to cancel a running or queued application run by run ID. - -SWR-TSSDK-4.4: Run Due Date Specification -Requirement Type: Software requirement (user) -Description: System shall accept optional due date timestamp when creating application runs to specify the expected completion time. - -SWR-TSSDK-4.5:Run Deadline Specification -Requirement Type: Software requirement (user) -Description: System shall accept optional deadline timestamp when creating application runs to specify when the -Platform API should automatically cancel the run if not completed. -SHR: TSSDK-5 - Application Results Access -Requirement Type: Stakeholder requirement (user) -Description: Users shall be able to access and retrieve results generated from AI application runs. - -SWR-TSSDK-5.1: Retrieve run items -Requirement Type: Software requirement (user) -Description: System shall retrieve items and their associated output artifacts for a specified application run by run ID. - -SWR-TSSDK-5.2: Item status information -Requirement Type: Software requirement (user) -Description: System shall provide execution state, output availability, termination status, and error details for each item. - -SWR-TSSDK-5.3: Artifact status information -Requirement Type: Software requirement (user) -Description: System shall provide execution state, download availability, termination status, and error details for each output artifact. - - -SHR: TSSDK-6 - Error Communication -Requirement Type: Stakeholder requirement (user) -Description: Users shall receive clear information when operations fail. - -SWR-TSSDK-6.1: Error Classification -Requirement Type: Software requirement (user) -Description: System shall assign a unique error code to each error to enable programmatic error handling and differentiation between error types. - -SWR-TSSDK-6.2: Error Messages -Requirement Type: Software requirement (user) -Description: System shall provide error messages that describe the failure cause and corrective action where applicable. - -SWR-TSSDK-6.3: Error Diagnostic Context -Requirement Type: Software requirement (user) -Description: System shall include diagnostic context in errors including protocol-specific status information for API failures and original error details for debugging. - -SWR-TSSDK-6.4: CLI Error Output -Requirement Type: Software requirement (user) -Description: CLI shall write error messages to standard error stream and provide machine-readable operation status through standard exit mechanisms. - - - - - - - - - - diff --git a/docs/requirements/SHR-TSSDK-2.md b/docs/requirements/SHR-APP-DISCOVERY.md similarity index 76% rename from docs/requirements/SHR-TSSDK-2.md rename to docs/requirements/SHR-APP-DISCOVERY.md index 3d58bdc..77915a1 100644 --- a/docs/requirements/SHR-TSSDK-2.md +++ b/docs/requirements/SHR-APP-DISCOVERY.md @@ -1,12 +1,12 @@ --- -itemId: SHR-TSSDK-2 +itemId: SHR-APP-DISCOVERY itemTitle: Application Discovery itemType: Requirement # Stakeholder requirement (user) Requirement type: FUNCTIONAL --- - + ## Description diff --git a/docs/requirements/SHR-TSSDK-3.md b/docs/requirements/SHR-APP-EXEC.md similarity index 79% rename from docs/requirements/SHR-TSSDK-3.md rename to docs/requirements/SHR-APP-EXEC.md index fbaadd1..c8bbcf4 100644 --- a/docs/requirements/SHR-TSSDK-3.md +++ b/docs/requirements/SHR-APP-EXEC.md @@ -1,12 +1,12 @@ --- -itemId: SHR-TSSDK-3 +itemId: SHR-APP-EXEC itemTitle: Application Execution Access itemType: Requirement # Stakeholder requirement (user) Requirement type: FUNCTIONAL --- - + ## Description diff --git a/docs/requirements/SHR-TSSDK-5.md b/docs/requirements/SHR-APP-RESULTS.md similarity index 78% rename from docs/requirements/SHR-TSSDK-5.md rename to docs/requirements/SHR-APP-RESULTS.md index a0eb8bd..c233866 100644 --- a/docs/requirements/SHR-TSSDK-5.md +++ b/docs/requirements/SHR-APP-RESULTS.md @@ -1,12 +1,12 @@ --- -itemId: SHR-TSSDK-5 +itemId: SHR-APP-RESULTS itemTitle: Application Results Access itemType: Requirement # Stakeholder requirement (user) Requirement type: FUNCTIONAL --- - + ## Description diff --git a/docs/requirements/SHR-TSSDK-4.md b/docs/requirements/SHR-APP-RUN-MGMT.md similarity index 78% rename from docs/requirements/SHR-TSSDK-4.md rename to docs/requirements/SHR-APP-RUN-MGMT.md index fe30f47..c2bb5dd 100644 --- a/docs/requirements/SHR-TSSDK-4.md +++ b/docs/requirements/SHR-APP-RUN-MGMT.md @@ -1,12 +1,12 @@ --- -itemId: SHR-TSSDK-4 +itemId: SHR-APP-RUN-MGMT itemTitle: Application Run Management itemType: Requirement # Stakeholder requirement (user) Requirement type: FUNCTIONAL --- - + ## Description diff --git a/docs/requirements/SHR-TSSDK-1.md b/docs/requirements/SHR-AUTH.md similarity index 79% rename from docs/requirements/SHR-TSSDK-1.md rename to docs/requirements/SHR-AUTH.md index 9ff0f4e..096d480 100644 --- a/docs/requirements/SHR-TSSDK-1.md +++ b/docs/requirements/SHR-AUTH.md @@ -1,12 +1,12 @@ --- -itemId: SHR-TSSDK-1 +itemId: SHR-AUTH itemTitle: Authenticated Platform Access itemType: Requirement # Stakeholder requirement (user) Requirement type: SECURITY --- - + ## Description diff --git a/docs/requirements/SHR-TSSDK-6.md b/docs/requirements/SHR-ERROR-COMM.md similarity index 75% rename from docs/requirements/SHR-TSSDK-6.md rename to docs/requirements/SHR-ERROR-COMM.md index dce6e0e..dddee56 100644 --- a/docs/requirements/SHR-TSSDK-6.md +++ b/docs/requirements/SHR-ERROR-COMM.md @@ -1,12 +1,12 @@ --- -itemId: SHR-TSSDK-6 +itemId: SHR-ERROR-COMM itemTitle: Error Communication itemType: Requirement # Stakeholder requirement (user) Requirement type: FUNCTIONAL --- - + ## Description diff --git a/docs/requirements/SWR-TSSDK-2-2.md b/docs/requirements/SWR-APP-DISCOVERY-DETAILS.md similarity index 82% rename from docs/requirements/SWR-TSSDK-2-2.md rename to docs/requirements/SWR-APP-DISCOVERY-DETAILS.md index db59f0f..a3590e9 100644 --- a/docs/requirements/SWR-TSSDK-2-2.md +++ b/docs/requirements/SWR-APP-DISCOVERY-DETAILS.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-2-2 +itemId: SWR-APP-DISCOVERY-DETAILS itemTitle: Application Details -itemHasParent: SHR-TSSDK-2 +itemHasParent: SHR-APP-DISCOVERY itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-2-1.md b/docs/requirements/SWR-APP-DISCOVERY-LIST.md similarity index 82% rename from docs/requirements/SWR-TSSDK-2-1.md rename to docs/requirements/SWR-APP-DISCOVERY-LIST.md index d3abe65..c997138 100644 --- a/docs/requirements/SWR-TSSDK-2-1.md +++ b/docs/requirements/SWR-APP-DISCOVERY-LIST.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-2-1 +itemId: SWR-APP-DISCOVERY-LIST itemTitle: Application List Retrieval -itemHasParent: SHR-TSSDK-2 +itemHasParent: SHR-APP-DISCOVERY itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-2-4.md b/docs/requirements/SWR-APP-DISCOVERY-VERSION-DETAILS.md similarity index 81% rename from docs/requirements/SWR-TSSDK-2-4.md rename to docs/requirements/SWR-APP-DISCOVERY-VERSION-DETAILS.md index 8f7f233..6b337f7 100644 --- a/docs/requirements/SWR-TSSDK-2-4.md +++ b/docs/requirements/SWR-APP-DISCOVERY-VERSION-DETAILS.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-2-4 +itemId: SWR-APP-DISCOVERY-VERSION-DETAILS itemTitle: Version Details -itemHasParent: SHR-TSSDK-2 +itemHasParent: SHR-APP-DISCOVERY itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-2-3.md b/docs/requirements/SWR-APP-DISCOVERY-VERSION-LIST.md similarity index 78% rename from docs/requirements/SWR-TSSDK-2-3.md rename to docs/requirements/SWR-APP-DISCOVERY-VERSION-LIST.md index 726d4e4..f5cca99 100644 --- a/docs/requirements/SWR-TSSDK-2-3.md +++ b/docs/requirements/SWR-APP-DISCOVERY-VERSION-LIST.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-2-3 +itemId: SWR-APP-DISCOVERY-VERSION-LIST itemTitle: Version List Retrieval -itemHasParent: SHR-TSSDK-2 +itemHasParent: SHR-APP-DISCOVERY itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-3-2.md b/docs/requirements/SWR-APP-EXEC-INPUT-ARTIFACT.md similarity index 83% rename from docs/requirements/SWR-TSSDK-3-2.md rename to docs/requirements/SWR-APP-EXEC-INPUT-ARTIFACT.md index 8c3c61a..b77c0d0 100644 --- a/docs/requirements/SWR-TSSDK-3-2.md +++ b/docs/requirements/SWR-APP-EXEC-INPUT-ARTIFACT.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-3-2 +itemId: SWR-APP-EXEC-INPUT-ARTIFACT itemTitle: Input Artifact Specification -itemHasParent: SHR-TSSDK-3 +itemHasParent: SHR-APP-EXEC itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-3-3.md b/docs/requirements/SWR-APP-EXEC-REQUEST-VALIDATION.md similarity index 79% rename from docs/requirements/SWR-TSSDK-3-3.md rename to docs/requirements/SWR-APP-EXEC-REQUEST-VALIDATION.md index 3aab995..4a79fdc 100644 --- a/docs/requirements/SWR-TSSDK-3-3.md +++ b/docs/requirements/SWR-APP-EXEC-REQUEST-VALIDATION.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-3-3 +itemId: SWR-APP-EXEC-REQUEST-VALIDATION itemTitle: Request Validation -itemHasParent: SHR-TSSDK-3 +itemHasParent: SHR-APP-EXEC itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-3-1.md b/docs/requirements/SWR-APP-EXEC-RUN-CREATION.md similarity index 85% rename from docs/requirements/SWR-TSSDK-3-1.md rename to docs/requirements/SWR-APP-EXEC-RUN-CREATION.md index 5a159b7..af9d37a 100644 --- a/docs/requirements/SWR-TSSDK-3-1.md +++ b/docs/requirements/SWR-APP-EXEC-RUN-CREATION.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-3-1 +itemId: SWR-APP-EXEC-RUN-CREATION itemTitle: Application Run Creation -itemHasParent: SHR-TSSDK-3 +itemHasParent: SHR-APP-EXEC itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-5-3.md b/docs/requirements/SWR-APP-RESULTS-ARTIFACT-STATUS.md similarity index 82% rename from docs/requirements/SWR-TSSDK-5-3.md rename to docs/requirements/SWR-APP-RESULTS-ARTIFACT-STATUS.md index fb18410..7b181fa 100644 --- a/docs/requirements/SWR-TSSDK-5-3.md +++ b/docs/requirements/SWR-APP-RESULTS-ARTIFACT-STATUS.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-5-3 +itemId: SWR-APP-RESULTS-ARTIFACT-STATUS itemTitle: Artifact Status Information -itemHasParent: SHR-TSSDK-5 +itemHasParent: SHR-APP-RESULTS itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-5-2.md b/docs/requirements/SWR-APP-RESULTS-ITEM-STATUS.md similarity index 82% rename from docs/requirements/SWR-TSSDK-5-2.md rename to docs/requirements/SWR-APP-RESULTS-ITEM-STATUS.md index a51046d..a7c1050 100644 --- a/docs/requirements/SWR-TSSDK-5-2.md +++ b/docs/requirements/SWR-APP-RESULTS-ITEM-STATUS.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-5-2 +itemId: SWR-APP-RESULTS-ITEM-STATUS itemTitle: Item Status Information -itemHasParent: SHR-TSSDK-5 +itemHasParent: SHR-APP-RESULTS itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-5-1.md b/docs/requirements/SWR-APP-RESULTS-RETRIEVE-ITEMS.md similarity index 81% rename from docs/requirements/SWR-TSSDK-5-1.md rename to docs/requirements/SWR-APP-RESULTS-RETRIEVE-ITEMS.md index eee246b..babd99c 100644 --- a/docs/requirements/SWR-TSSDK-5-1.md +++ b/docs/requirements/SWR-APP-RESULTS-RETRIEVE-ITEMS.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-5-1 +itemId: SWR-APP-RESULTS-RETRIEVE-ITEMS itemTitle: Retrieve Run Items -itemHasParent: SHR-TSSDK-5 +itemHasParent: SHR-APP-RESULTS itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-4-3.md b/docs/requirements/SWR-APP-RUN-MGMT-CANCEL.md similarity index 81% rename from docs/requirements/SWR-TSSDK-4-3.md rename to docs/requirements/SWR-APP-RUN-MGMT-CANCEL.md index f3e9bd4..805b763 100644 --- a/docs/requirements/SWR-TSSDK-4-3.md +++ b/docs/requirements/SWR-APP-RUN-MGMT-CANCEL.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-4-3 +itemId: SWR-APP-RUN-MGMT-CANCEL itemTitle: Cancel Application Run -itemHasParent: SHR-TSSDK-4 +itemHasParent: SHR-APP-RUN-MGMT itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-4-5.md b/docs/requirements/SWR-APP-RUN-MGMT-DEADLINE.md similarity index 85% rename from docs/requirements/SWR-TSSDK-4-5.md rename to docs/requirements/SWR-APP-RUN-MGMT-DEADLINE.md index 9eda3e3..99bfc7a 100644 --- a/docs/requirements/SWR-TSSDK-4-5.md +++ b/docs/requirements/SWR-APP-RUN-MGMT-DEADLINE.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-4-5 +itemId: SWR-APP-RUN-MGMT-DEADLINE itemTitle: Run Deadline Specification -itemHasParent: SHR-TSSDK-4 +itemHasParent: SHR-APP-RUN-MGMT itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-4-2.md b/docs/requirements/SWR-APP-RUN-MGMT-DETAILS.md similarity index 81% rename from docs/requirements/SWR-TSSDK-4-2.md rename to docs/requirements/SWR-APP-RUN-MGMT-DETAILS.md index 64191a5..28830ec 100644 --- a/docs/requirements/SWR-TSSDK-4-2.md +++ b/docs/requirements/SWR-APP-RUN-MGMT-DETAILS.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-4-2 +itemId: SWR-APP-RUN-MGMT-DETAILS itemTitle: Retrieve Run Details -itemHasParent: SHR-TSSDK-4 +itemHasParent: SHR-APP-RUN-MGMT itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-4-4.md b/docs/requirements/SWR-APP-RUN-MGMT-DUE-DATE.md similarity index 84% rename from docs/requirements/SWR-TSSDK-4-4.md rename to docs/requirements/SWR-APP-RUN-MGMT-DUE-DATE.md index 67e5933..5d413a9 100644 --- a/docs/requirements/SWR-TSSDK-4-4.md +++ b/docs/requirements/SWR-APP-RUN-MGMT-DUE-DATE.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-4-4 +itemId: SWR-APP-RUN-MGMT-DUE-DATE itemTitle: Run Due Date Specification -itemHasParent: SHR-TSSDK-4 +itemHasParent: SHR-APP-RUN-MGMT itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-4-1.md b/docs/requirements/SWR-APP-RUN-MGMT-LIST.md similarity index 83% rename from docs/requirements/SWR-TSSDK-4-1.md rename to docs/requirements/SWR-APP-RUN-MGMT-LIST.md index 837217e..03159d5 100644 --- a/docs/requirements/SWR-TSSDK-4-1.md +++ b/docs/requirements/SWR-APP-RUN-MGMT-LIST.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-4-1 +itemId: SWR-APP-RUN-MGMT-LIST itemTitle: List Application Runs -itemHasParent: SHR-TSSDK-4 +itemHasParent: SHR-APP-RUN-MGMT itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-1-6.md b/docs/requirements/SWR-AUTH-AUTO-REFRESH.md similarity index 85% rename from docs/requirements/SWR-TSSDK-1-6.md rename to docs/requirements/SWR-AUTH-AUTO-REFRESH.md index 3aa60c6..c27b406 100644 --- a/docs/requirements/SWR-TSSDK-1-6.md +++ b/docs/requirements/SWR-AUTH-AUTO-REFRESH.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-1-6 +itemId: SWR-AUTH-AUTO-REFRESH itemTitle: Automatic Token Refresh -itemHasParent: SHR-TSSDK-1 +itemHasParent: SHR-AUTH itemType: Requirement # Software requirement (system) Requirement type: SECURITY diff --git a/docs/requirements/SWR-TSSDK-1-3.md b/docs/requirements/SWR-AUTH-CODE-FLOW.md similarity index 87% rename from docs/requirements/SWR-TSSDK-1-3.md rename to docs/requirements/SWR-AUTH-CODE-FLOW.md index b6bde7b..d68ac08 100644 --- a/docs/requirements/SWR-TSSDK-1-3.md +++ b/docs/requirements/SWR-AUTH-CODE-FLOW.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-1-3 +itemId: SWR-AUTH-CODE-FLOW itemTitle: Secure Authorisation Code Authentication -itemHasParent: SHR-TSSDK-1 +itemHasParent: SHR-AUTH itemType: Requirement # Software requirement (system) Requirement type: SECURITY diff --git a/docs/requirements/SWR-TSSDK-1-4.md b/docs/requirements/SWR-AUTH-CUSTOM-PROVIDER.md similarity index 81% rename from docs/requirements/SWR-TSSDK-1-4.md rename to docs/requirements/SWR-AUTH-CUSTOM-PROVIDER.md index d015c72..dc687b4 100644 --- a/docs/requirements/SWR-TSSDK-1-4.md +++ b/docs/requirements/SWR-AUTH-CUSTOM-PROVIDER.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-1-4 +itemId: SWR-AUTH-CUSTOM-PROVIDER itemTitle: Custom Token Provider -itemHasParent: SHR-TSSDK-1 +itemHasParent: SHR-AUTH itemType: Requirement # Software requirement (system) Requirement type: SECURITY diff --git a/docs/requirements/SWR-TSSDK-1-5.md b/docs/requirements/SWR-AUTH-SECURE-STORAGE.md similarity index 82% rename from docs/requirements/SWR-TSSDK-1-5.md rename to docs/requirements/SWR-AUTH-SECURE-STORAGE.md index 0313905..1d72b1b 100644 --- a/docs/requirements/SWR-TSSDK-1-5.md +++ b/docs/requirements/SWR-AUTH-SECURE-STORAGE.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-1-5 +itemId: SWR-AUTH-SECURE-STORAGE itemTitle: Secure Token Storage -itemHasParent: SHR-TSSDK-1 +itemHasParent: SHR-AUTH itemType: Requirement # Software requirement (system) Requirement type: SECURITY diff --git a/docs/requirements/SWR-TSSDK-1-1.md b/docs/requirements/SWR-AUTH-TOKEN-BASED.md similarity index 81% rename from docs/requirements/SWR-TSSDK-1-1.md rename to docs/requirements/SWR-AUTH-TOKEN-BASED.md index 86c1dc1..5a742ff 100644 --- a/docs/requirements/SWR-TSSDK-1-1.md +++ b/docs/requirements/SWR-AUTH-TOKEN-BASED.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-1-1 +itemId: SWR-AUTH-TOKEN-BASED itemTitle: Token-Based Authentication -itemHasParent: SHR-TSSDK-1 +itemHasParent: SHR-AUTH itemType: Requirement # Software requirement (system) Requirement type: SECURITY diff --git a/docs/requirements/SWR-TSSDK-1-7.md b/docs/requirements/SWR-AUTH-TOKEN-REMOVAL.md similarity index 80% rename from docs/requirements/SWR-TSSDK-1-7.md rename to docs/requirements/SWR-AUTH-TOKEN-REMOVAL.md index 3fc0638..4e4a531 100644 --- a/docs/requirements/SWR-TSSDK-1-7.md +++ b/docs/requirements/SWR-AUTH-TOKEN-REMOVAL.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-1-7 +itemId: SWR-AUTH-TOKEN-REMOVAL itemTitle: Token Removal -itemHasParent: SHR-TSSDK-1 +itemHasParent: SHR-AUTH itemType: Requirement # Software requirement (user) Requirement type: SECURITY diff --git a/docs/requirements/SWR-TSSDK-1-2.md b/docs/requirements/SWR-AUTH-VALIDATION.md similarity index 83% rename from docs/requirements/SWR-TSSDK-1-2.md rename to docs/requirements/SWR-AUTH-VALIDATION.md index dda23ef..c3afeed 100644 --- a/docs/requirements/SWR-TSSDK-1-2.md +++ b/docs/requirements/SWR-AUTH-VALIDATION.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-1-2 +itemId: SWR-AUTH-VALIDATION itemTitle: Authentication Validation -itemHasParent: SHR-TSSDK-1 +itemHasParent: SHR-AUTH itemType: Requirement # Software requirement (system) Requirement type: SECURITY diff --git a/docs/requirements/SWR-TSSDK-6-1.md b/docs/requirements/SWR-ERROR-COMM-CLASSIFICATION.md similarity index 82% rename from docs/requirements/SWR-TSSDK-6-1.md rename to docs/requirements/SWR-ERROR-COMM-CLASSIFICATION.md index e209146..8087438 100644 --- a/docs/requirements/SWR-TSSDK-6-1.md +++ b/docs/requirements/SWR-ERROR-COMM-CLASSIFICATION.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-6-1 +itemId: SWR-ERROR-COMM-CLASSIFICATION itemTitle: Error Classification -itemHasParent: SHR-TSSDK-6 +itemHasParent: SHR-ERROR-COMM itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-6-4.md b/docs/requirements/SWR-ERROR-COMM-CLI-OUTPUT.md similarity index 82% rename from docs/requirements/SWR-TSSDK-6-4.md rename to docs/requirements/SWR-ERROR-COMM-CLI-OUTPUT.md index d6667f5..2770769 100644 --- a/docs/requirements/SWR-TSSDK-6-4.md +++ b/docs/requirements/SWR-ERROR-COMM-CLI-OUTPUT.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-6-4 +itemId: SWR-ERROR-COMM-CLI-OUTPUT itemTitle: CLI Error Output -itemHasParent: SHR-TSSDK-6 +itemHasParent: SHR-ERROR-COMM itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-6-3.md b/docs/requirements/SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md similarity index 83% rename from docs/requirements/SWR-TSSDK-6-3.md rename to docs/requirements/SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md index 154462e..e292422 100644 --- a/docs/requirements/SWR-TSSDK-6-3.md +++ b/docs/requirements/SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-6-3 +itemId: SWR-ERROR-COMM-DIAGNOSTIC-CONTEXT itemTitle: Error Diagnostic Context -itemHasParent: SHR-TSSDK-6 +itemHasParent: SHR-ERROR-COMM itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/SWR-TSSDK-6-2.md b/docs/requirements/SWR-ERROR-COMM-MESSAGES.md similarity index 82% rename from docs/requirements/SWR-TSSDK-6-2.md rename to docs/requirements/SWR-ERROR-COMM-MESSAGES.md index e9f38dc..2f87561 100644 --- a/docs/requirements/SWR-TSSDK-6-2.md +++ b/docs/requirements/SWR-ERROR-COMM-MESSAGES.md @@ -1,7 +1,7 @@ --- -itemId: SWR-TSSDK-6-2 +itemId: SWR-ERROR-COMM-MESSAGES itemTitle: Error Messages -itemHasParent: SHR-TSSDK-6 +itemHasParent: SHR-ERROR-COMM itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL diff --git a/docs/requirements/TEMPLATE_SHR.md b/docs/requirements/TEMPLATE_SHR.md index 385d33e..e8930c9 100644 --- a/docs/requirements/TEMPLATE_SHR.md +++ b/docs/requirements/TEMPLATE_SHR.md @@ -1,4 +1,4 @@ -# SHR Template - Stakeholder Health Requirement +# SHR Template - Stakeholder Requirement **Purpose**: Use this template to create Stakeholder Requirements (SHR) - high-level requirements that describe what stakeholders need from the system. @@ -6,13 +6,15 @@ ```markdown --- -itemId: SHR-[MODULE]-[NUMBER] +itemId: SHR-[DESCRIPTIVE-NAME] itemTitle: [Brief Descriptive Title] itemType: Requirement # Stakeholder requirement (user) -Requirement type: [ENVIRONMENT|FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABILITY] +Requirement type: [FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABILITY] --- + + ## Description [Detailed description of the stakeholder requirement. This should clearly state what users/stakeholders need to be able to do or what the system needs to provide. Write in complete sentences describing the capability or need from the stakeholder's perspective.] @@ -22,10 +24,12 @@ Requirement type: [ENVIRONMENT|FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABIL ### YAML Frontmatter (Required) -- **itemId**: Unique identifier following pattern `SHR-[MODULE]-[NUMBER]` - - `[MODULE]`: The system module or domain (e.g., APPLICATION, SYSTEM, BUCKET, DATASET, VISUALIZATION) - - `[NUMBER]`: Sequential number starting from 1 for each module - - Example: `SHR-APPLICATION-1`, `SHR-SYSTEM-2` +- **itemId**: Unique identifier following pattern `SHR-[DESCRIPTIVE-NAME]` + - `[DESCRIPTIVE-NAME]`: Hyphenated descriptive identifier using module prefix and feature name + - Should be clear, concise, and self-documenting + - Use uppercase with hyphens (kebab-case in uppercase) + - Common module prefixes: APP, AUTH, SYSTEM, BUCKET, DATASET, ERROR, API + - Example: `SHR-APP-DISCOVERY`, `SHR-AUTH`, `SHR-ERROR-COMM`, `SHR-APP-RUN-MGMT` - **itemTitle**: Short, descriptive title (3-8 words recommended) - Should be clear and specific @@ -35,13 +39,14 @@ Requirement type: [ENVIRONMENT|FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABIL - **itemType**: Always set to `Requirement` for requirements documents - **Requirement type**: Choose one based on the nature of the requirement: - - `ENVIRONMENT`: Requirements about the operating context, user workflows, or system environment - - `FUNCTIONAL`: Requirements describing specific system functions or capabilities + - `FUNCTIONAL`: Requirements describing specific system functions or capabilities (most common) - `REGULATORY`: Requirements derived from regulations, standards, or compliance needs - `PERFORMANCE`: Requirements about system performance, speed, or efficiency - `SECURITY`: Requirements about system security, access control, or data protection - `USABILITY`: Requirements about user experience, accessibility, or ease of use + Note: ENVIRONMENT type has been removed - use FUNCTIONAL for user workflows and system context requirements + ### Description Section (Required) - **Format**: Markdown heading level 2 (`## Description`) @@ -58,67 +63,74 @@ Requirement type: [ENVIRONMENT|FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABIL ### Example 1: User-Facing Capability ```markdown --- -itemId: SHR-APPLICATION-1 -itemTitle: Application Discovery and Navigation +itemId: SHR-APP-DISCOVERY +itemTitle: Application Discovery itemType: Requirement # Stakeholder requirement (user) -Requirement type: ENVIRONMENT +Requirement type: FUNCTIONAL --- + + ## Description -Users shall be able to view available AI applications and navigate to specific application views to access application functionality. +Users shall be able to discover available AI applications and their versions. ``` -### Example 2: System Capability with Detail +### Example 2: Security Requirement ```markdown --- -itemId: SHR-SYSTEM-1 -itemTitle: System Health Monitoring and Observability +itemId: SHR-AUTH +itemTitle: Authenticated Platform Access itemType: Requirement # Stakeholder requirement (user) -Requirement type: ENVIRONMENT +Requirement type: SECURITY --- + + ## Description -Users shall be able to monitor the operational health and status of the system through multiple interfaces to ensure system reliability, diagnose issues, and maintain confidence in system availability. The system shall provide transparent, real-time visibility into its operational state across all user interaction points. +Access to the Aignostics Platform shall require valid user authentication credentials. ``` -### Example 3: Workflow Requirement +### Example 3: Error Handling Requirement ```markdown --- -itemId: SHR-APPLICATION-2 -itemTitle: Application Run Management +itemId: SHR-ERROR-COMM +itemTitle: Error Communication itemType: Requirement # Stakeholder requirement (user) -Requirement type: ENVIRONMENT +Requirement type: FUNCTIONAL --- + + ## Description -Users shall be able to execute AI applications on their data by preparing data, submitting runs, monitoring run status, managing run lifecycle including cancellation, and accessing results. +Users shall receive clear information when operations fail. ``` ## Naming Conventions -### Module Names -Use clear, consistent module names that reflect your system architecture: -- APPLICATION (for application management features) +### Module Prefixes +Use clear, consistent module prefixes that reflect your system architecture: +- APP (for application-related features) +- AUTH (for authentication/authorization) - SYSTEM (for system-wide capabilities) - BUCKET (for storage management) - DATASET (for data operations) -- VISUALIZATION (for visualization tools) -- USER (for user management) -- AUTH (for authentication/authorization) +- ERROR (for error handling and communication) - API (for API-specific requirements) +- USER (for user management) - etc. -### Numbering -- Start from 1 for each module -- Increment sequentially (1, 2, 3, ...) -- Use the same number space across all requirement types for the module -- Example: SHR-APPLICATION-1, SHR-APPLICATION-2, SHR-APPLICATION-3 +### Descriptive Names +- Use hyphenated uppercase names (e.g., `SHR-APP-DISCOVERY`, `SHR-APP-RUN-MGMT`) +- Combine module prefix with feature name +- Keep names concise but descriptive +- Use common abbreviations where clear (MGMT for Management, EXEC for Execution, COMM for Communication) +- Example: `SHR-APP-DISCOVERY`, `SHR-AUTH`, `SHR-ERROR-COMM`, `SHR-APP-RESULTS` ## Best Practices @@ -132,15 +144,16 @@ Use clear, consistent module names that reflect your system architecture: ## Validation Checklist Before finalizing an SHR, verify: -- [ ] itemId follows SHR-[MODULE]-[NUMBER] pattern +- [ ] itemId follows SHR-[DESCRIPTIVE-NAME] pattern (e.g., SHR-APP-DISCOVERY) - [ ] itemTitle is clear and descriptive - [ ] itemType is set to "Requirement" -- [ ] Requirement type is one of the valid values +- [ ] Requirement type is one of the valid values (FUNCTIONAL, SECURITY, etc.) - [ ] Description section exists with ## heading - [ ] Description explains WHAT stakeholders need (not HOW) - [ ] Language is clear and unambiguous - [ ] Requirement is testable/verifiable - [ ] YAML frontmatter is properly formatted +- [ ] Optional comment included for original reference if migrating ## Notes for AI Agents diff --git a/docs/requirements/TEMPLATE_SWR.md b/docs/requirements/TEMPLATE_SWR.md index 7014ad3..23f87ad 100644 --- a/docs/requirements/TEMPLATE_SWR.md +++ b/docs/requirements/TEMPLATE_SWR.md @@ -6,15 +6,17 @@ ```markdown --- -itemId: SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME] +itemId: SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX] itemTitle: [Brief Descriptive Title] -itemHasParent: SHR-[MODULE]-[PARENT_NUMBER] +itemHasParent: SHR-[PARENT-NAME] itemType: Requirement # Software requirement (user|system) Requirement type: [FUNCTIONAL|REGULATORY|PERFORMANCE|SECURITY|USABILITY] Layer: [System (backend logic)|User Interface (frontend)|GUI|CLI|API|Database|etc.] --- + + [Detailed requirement description. Can be written as a plain statement or as a user story. Should clearly specify the technical implementation requirement.] ``` @@ -22,20 +24,20 @@ Layer: [System (backend logic)|User Interface (frontend)|GUI|CLI|API|Database|et ### YAML Frontmatter (Required) -- **itemId**: Unique identifier following pattern `SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME]` - - `[MODULE]`: Same module as parent SHR (e.g., APPLICATION, SYSTEM, BUCKET) - - `[PARENT_NUMBER]`: The number from the parent SHR (e.g., if parent is SHR-APPLICATION-2, use 2) - - `[DESCRIPTIVE_NAME]`: Short descriptive name or sequential number (e.g., LIST-APPS, 1, 2) - - Example: `SWR-APPLICATION-1-LIST`, `SWR-APPLICATION-2-1`, `SWR-SYSTEM-1-GUI-HEALTH` +- **itemId**: Unique identifier following pattern `SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX]` + - `[PARENT-NAME]`: The full descriptive name from parent SHR (e.g., APP-DISCOVERY, AUTH, ERROR-COMM) + - `[DESCRIPTIVE-SUFFIX]`: Short descriptive identifier for this specific requirement + - Use hyphenated uppercase names + - Example: `SWR-APP-DISCOVERY-LIST`, `SWR-APP-DISCOVERY-DETAILS`, `SWR-AUTH-TOKEN-BASED`, `SWR-ERROR-COMM-CLI-OUTPUT` - **itemTitle**: Short, descriptive title (3-8 words recommended) - Should be specific about the technical requirement - Use title case - Example: "List Available Applications", "Accept Optional Run Name and Description" -- **itemHasParent**: Reference to parent SHR using format `SHR-[MODULE]-[NUMBER]` - - Must match an existing SHR itemId - - Example: `SHR-APPLICATION-1`, `SHR-SYSTEM-2` +- **itemHasParent**: Reference to parent SHR using format `SHR-[PARENT-NAME]` + - Must match an existing SHR itemId exactly + - Example: `SHR-APP-DISCOVERY`, `SHR-AUTH`, `SHR-ERROR-COMM` - **itemType**: Always set to `Requirement` for requirements documents @@ -94,104 +96,109 @@ Layer: [System (backend logic)|User Interface (frontend)|GUI|CLI|API|Database|et ### Example 1: Simple Backend Requirement ```markdown --- -itemId: SWR-APPLICATION-1-1 +itemId: SWR-APP-DISCOVERY-LIST itemTitle: List Available Applications -itemHasParent: SHR-APPLICATION-1 +itemHasParent: SHR-APP-DISCOVERY itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL Layer: System (backend logic) --- + + System shall provide a list of available applications for user selection. ``` -### Example 2: GUI Requirement with User Story +### Example 2: CLI Requirement ```markdown --- -itemId: SWR-SYSTEM-GUI-HEALTH-1 -itemTitle: GUI System Health Visibility -itemHasParent: SHR-SYSTEM-1 +itemId: SWR-ERROR-COMM-CLI-OUTPUT +itemTitle: CLI Error Output +itemHasParent: SHR-ERROR-COMM itemType: Requirement -# Software requirement (system) -Requirement type: REGULATORY -Layer: GUI +# Software requirement (user) +Requirement type: FUNCTIONAL +Layer: CLI --- -As a user, I expected the current health of Launchpad being always visible in the footer of the GUI so that I can ensure the system is operational. + + +CLI shall write error messages to standard error stream and provide machine-readable operation status through standard exit mechanisms. ``` -### Example 3: Detailed Requirement with Validation +### Example 3: Authentication Requirement ```markdown --- -itemId: SWR-APPLICATION-2-13 -itemTitle: Accept Optional Run Name and Description -itemHasParent: SHR-APPLICATION-2 +itemId: SWR-AUTH-TOKEN-BASED +itemTitle: Token-Based Authentication +itemHasParent: SHR-AUTH itemType: Requirement -# Software requirement (user) -Requirement type: FUNCTIONAL -Layer: System (backend logic) +# Software requirement (system) +Requirement type: SECURITY --- -System shall accept optional user-provided run name and description during application run submission. The system shall validate that run names do not exceed 100 characters and descriptions do not exceed 500 characters when provided, and shall store these metadata fields with the run record. + + +System shall authenticate API requests using access tokens. ``` -### Example 4: Storage Operation Requirement +### Example 4: Detailed Application Requirement ```markdown --- -itemId: SWR-BUCKET-1-1 -itemTitle: Upload Directory Structure to Bucket Storage -itemHasParent: SHR-BUCKET-1 +itemId: SWR-APP-DISCOVERY-DETAILS +itemTitle: Application Details +itemHasParent: SHR-APP-DISCOVERY itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL Layer: System (backend logic) --- -System shall upload local directory structures with multiple files and subdirectories to bucket storage while preserving file organization. + + +System shall provide application identification, description, and regulatory compliance information for each retrieved application. ``` -### Example 5: Complex Multi-Granularity Requirement +### Example 5: Request Validation Requirement ```markdown --- -itemId: SWR-APPLICATION-3-1 -itemTitle: Download Application Run Results -itemHasParent: SHR-APPLICATION-3 +itemId: SWR-APP-EXEC-REQUEST-VALIDATION +itemTitle: Request Validation +itemHasParent: SHR-APP-EXEC itemType: Requirement # Software requirement (user) Requirement type: FUNCTIONAL Layer: System (backend logic) --- -System shall download application run results at multiple granularity levels: all items per run, individual items, and individual artifacts per item. The system shall download to specified destination directories when requested by run identifier, retrieve results regardless of run status, and provide download confirmation with status information indicating whether run was completed or canceled. + + +System shall validate run request format before submission to the platform. ``` ## Naming Conventions ### itemId Pattern -`SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME]` - -**Descriptive Name Options**: -1. **Sequential numbers**: 1, 2, 3, etc. - - Example: SWR-APPLICATION-1-1, SWR-APPLICATION-1-2 - - Pro: Simple, easy to generate - - Con: Less self-documenting +`SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX]` -2. **Short descriptive keywords**: LIST, UPLOAD, DELETE, etc. - - Example: SWR-APPLICATION-1-LIST, SWR-BUCKET-1-UPLOAD - - Pro: More readable, self-documenting - - Con: Requires consistent naming +**Structure**: +1. **Parent Name**: Must exactly match the parent SHR's descriptive name + - Example: If parent is `SHR-APP-DISCOVERY`, use `SWR-APP-DISCOVERY-*` -3. **Combined approach**: Use descriptive names for major features, numbers for variations - - Example: SWR-APPLICATION-2-SUBMIT-1, SWR-APPLICATION-2-SUBMIT-2 - - Pro: Balances clarity and simplicity - - Con: More complex to manage +2. **Descriptive Suffix**: Short identifier specific to this requirement + - Use descriptive keywords: LIST, DETAILS, CREATE, DELETE, VALIDATION, etc. + - Keep it concise but meaningful + - Use hyphens for multi-word suffixes -**Recommendation**: Use sequential numbers unless descriptive names add significant clarity. +**Examples**: +- `SWR-APP-DISCOVERY-LIST` (parent: SHR-APP-DISCOVERY) +- `SWR-APP-DISCOVERY-DETAILS` (parent: SHR-APP-DISCOVERY) +- `SWR-AUTH-TOKEN-BASED` (parent: SHR-AUTH) +- `SWR-ERROR-COMM-CLI-OUTPUT` (parent: SHR-ERROR-COMM) +- `SWR-APP-EXEC-REQUEST-VALIDATION` (parent: SHR-APP-EXEC) -### Module and Parent Number -- Must match the parent SHR -- Example: If parent is `SHR-APPLICATION-2`, then SWR prefix is `SWR-APPLICATION-2-*` +**Recommendation**: Use descriptive suffixes that clearly indicate the specific functionality being implemented. ## Relationship to SHR @@ -203,10 +210,11 @@ Each SWR must: **Example Breakdown**: ``` -SHR-APPLICATION-1: "Application Discovery and Navigation" -├── SWR-APPLICATION-1-1: "List Available Applications" -├── SWR-APPLICATION-1-2: "Display Application Details" -└── SWR-APPLICATION-1-3: "Navigate to Application View" +SHR-APP-DISCOVERY: "Application Discovery" +├── SWR-APP-DISCOVERY-LIST: "List Available Applications" +├── SWR-APP-DISCOVERY-DETAILS: "Application Details" +├── SWR-APP-DISCOVERY-VERSION-LIST: "List Application Versions" +└── SWR-APP-DISCOVERY-VERSION-DETAILS: "Application Version Details" ``` ## Layer Guidelines @@ -259,16 +267,18 @@ System shall [action1] at multiple [scope] levels: [option1], [option2], and [op ## Validation Checklist Before finalizing an SWR, verify: -- [ ] itemId follows SWR-[MODULE]-[PARENT_NUMBER]-[DESCRIPTIVE_NAME] pattern +- [ ] itemId follows SWR-[PARENT-NAME]-[DESCRIPTIVE-SUFFIX] pattern +- [ ] itemId parent name exactly matches the parent SHR's name - [ ] itemTitle is clear and descriptive -- [ ] itemHasParent references a valid SHR +- [ ] itemHasParent references a valid SHR (exact match) - [ ] itemType is set to "Requirement" - [ ] Software requirement type (user|system) is specified - [ ] Requirement type is one of the valid values -- [ ] Layer is specified (if applicable) +- [ ] Layer is specified (optional but recommended) - [ ] Requirement description is clear and implementable - [ ] Requirement is testable/verifiable - [ ] YAML frontmatter is properly formatted +- [ ] Optional comment included for original reference if migrating - [ ] Requirement implements part of the parent SHR ## Notes for AI Agents