ara-cli 0.1.9.69__py3-none-any.whl → 0.1.10.8__py3-none-any.whl

ara_cli/templates/prompt-modules/commands/prompt_template_tech_stack_transformer.commands.md

@@ -0,0 +1,95 @@
+# Tech Stack Prompt Template Transformer
+
+## PROMPT:
+You are a prompt template transformation specialist. Your task is to transform Python-specific prompt templates into equivalent templates for a different technology stack while maintaining the same structure, intent, and quality standards.
+
+### INPUT REQUIREMENTS:
+1. **Target Technology Stack** (MANDATORY): The technology stack to transform to (e.g., 'C#', 'Java', 'React', 'TypeScript', 'Go', 'Rust', etc.)
+2. **Source Prompt Templates** (MANDATORY): One or more Python prompt templates to transform
+
+### TRANSFORMATION RULES:
+1. **Preserve Structure and Intent**:
+   - Maintain the same logical flow and purpose of each prompt template
+   - Keep all sections and their hierarchical organization
+   - Preserve the extract/filename format for code generation
+
+2. **Technology-Specific Adaptations**:
+   - Replace Python-specific references with target technology equivalents
+   - Update file extensions (.py → appropriate extension for target stack)
+   - Adapt coding standards (PEP8 → target language conventions)
+   - Replace Python packages with target language equivalents
+   - Update testing frameworks (pytest/behave → target language testing tools)
+   - Adapt documentation styles (numpy docstrings → target language documentation)
+   - Update logging approaches to target language standards
+   - Adjust line/method/class length limits based on target language best practices. Prefer lower length limits.
+
+3. **Naming Convention**:
+   - Prefix each transformed template filename with the target technology
+   - Example: `python_bug_fixing_code.commands.md` → `csharp_bug_fixing_code.commands.md`
+
+4. **Output Format**:
+   - Return each transformed template as a complete, copy-pastable markdown file in 5-backticks
+   - The first character of the first line inside your code block must be '#' and the first character of the second line inside your code block must be '#'
+   - Use this format for each transformed template:
+
+`````markdown
+# [ ] extract
+# filename: ara/.araconfig/custom-prompt-modules/commands/{technology}_{original_template_name}
+{transformed template content}
+`````
+
+5. Markdown code block handling in prompt templates
+   The first and the second line of the Markdown code blocks used in the prompt templates serve as extraction control commands. the '#' tags in the first and second line of the code blocks must not be replaced by any other symbols, independent of the technology for which the markdown code block response is defined 
+
+6. **Technology Mapping Guidelines**:
+   **For C#/.NET:**
+   - PEP8 → C# Coding Conventions (Microsoft guidelines)
+   - pytest → NUnit/xUnit/MSTest
+   - behave → SpecFlow
+   - unittest.mock → Moq/NSubstitute
+   - numpy docstrings → XML documentation comments
+   - logging package → ILogger/Serilog/NLog
+
+   **For Java:**
+   - PEP8 → Java Code Conventions (Oracle/Google style)
+   - pytest → JUnit/TestNG
+   - behave → Cucumber-JVM
+   - unittest.mock → Mockito/EasyMock
+   - numpy docstrings → Javadoc
+   - logging package → SLF4J/Log4j
+
+   **For JavaScript/TypeScript:**
+   - PEP8 → ESLint/Prettier standards
+   - pytest → Jest/Mocha/Vitest
+   - behave → Cucumber.js, Selenium
+   - unittest.mock → Jest mocks/Sinon
+   - numpy docstrings → JSDoc/TSDoc
+   - logging package → Winston/Bunyan/Pino
+
+   **For React:**
+   - Include React-specific patterns (components, hooks, state management)
+   - pytest → Jest/React Testing Library
+   - behave → Selenium 
+   - Add component testing guidelines
+   - Include JSX/TSX specific rules
+
+7. **Preserve Key Constraints**:
+   - Maintain separation of concerns and single responsibility principles
+   - Keep modular/extensible design requirements
+   - Preserve testability requirements
+   - Maintain observability/logging requirements
+
+### VALIDATION:
+- Ensure all Python-specific references are properly transformed
+- Verify file paths and extensions match target technology conventions
+- Confirm testing and mocking frameworks are appropriate for target stack
+- Check that documentation styles match target language standards
+
+### OUTPUT SPECIFICATION:
+- Replace '# [ ] extract' with '# [x] extract' in all output blocks
+- Ensure each template is complete and ready for extraction
+- Include a summary of key transformations made for each template
+
+---
+
+**Begin transformation after receiving target technology stack and source templates.**

ara_cli/templates/prompt-modules/commands/python_bug_fixing_code.commands.md

@@ -0,0 +1,34 @@
+### COMMANDS FOR FIXING BUGS
+
+Your job is now to fix the described error:
+
+* Silently analyze the given error description or error log files
+* Silently review the provided source files and if given the provided feature file (specified behavior) to understand the current faulty implementation and draft silently a potential solution to fix the error
+* Develop implementation strategies that minimize code changes, prefer reusing existing methods over new implementations. Also always prefer to use existing python packages over your own implementation.
+
+When you touch code or need to generate code for bug fixing:
+* The max function or method length should not exceed 40 lines.
+* The max class length should not exceed 150 lines.
+* The max file length should not exceed 150 lines.
+* Split implementation files or functions/methods/classes in case they exceed their defined length maximum.
+* Apply as coding and design principle the separation of concerns and single responsibility principle in general and specifically when you need to split.
+
+* Important: you are NOT allowed to do any further refactorings not related to the bug fixing implementation. Refactoring for enhancing the code quality is not allowed.
+* The fixed code must fully implement the specified behavior in an easy testable and modular/extensible way.
+* Follow PEP8 coding guidelines.
+* Use descriptive numpy style docstrings for inline method and class documentation.
+* Use the python logger logging package to implement logging for all application modules that enables a fine granular full observability of the program flow by the log file. Use ./logs/<module_name>.log as filepath for logging.
+
+* Only return full copy pastable file content.
+* Use for every single generated code block this markdown code block format:
+
+```python
+# [ ] extract
+# filename: src/{filename}.py
+{python code}
+```
+
+* The extract and filename statements are only allowed once per code block
+* The first character of the first line inside your code block must be '#' and the first character of the second line inside your code block must be '#'
+* replace the '# [ ] extract' statement of the template with '# [x] extract' in your response
+* in case of files get deprecated give me a list of files that can be safely deleted

ara_cli/templates/prompt-modules/commands/python_generate_code.commands.md

@@ -0,0 +1,27 @@
+### COMMANDS FOR IMPLEMENTING ONE OR A SET OF NEW OR CHANGED FEATURE FILES
+
+Your job is now:
+* Silently analyze the given feature files and the specified behavior.
+* Develop implementation strategies that minimize code changes with respect to any given code and test files, prefer reusing existing methods over new implementations.
+* The max function length should not exceed 25 lines. The max file length should not exceed 120 lines.
+* Always prefer to use existing python packages over your own implementation.
+* In case additional implementation instructions are given as:
+  * Specified in files with extensions "*.technology.md" follow strictly the specified mandatory python packages and tech stack
+  * Explicitly specified as example reference implementation: use this reference information as starting point for your own implementation
+* Fully implement the specified behavior in an easy testable and modular/extensible way, fully implement unit tests for your production code (try to achieve at least 90% code coverage) and implement for all given feature files the corresponding step definitions. Follow PEP8 coding guidelines, use numpy style docstrings for inline function documentation, apply as coding and design principle the separation of concerns and single responsibility principle.
+* Generated or reworked python methods must not exceed 25 lines of code. In case methods exceed this length they need to be split according to the single responsibility principle and separation of concerns.
+* Generated or reworked python files must not exceed 120 lines of code. In case files exceed this length they need to be split according to the single responsibility principle and separation of concerns.
+* Use the python logger logging package to implement logging for all application modules that enable a full observability of the program flow over the log file. Use ./logs/<module_name>.log as filepath for logging.
+
+* Only return full copy pastable file content for production code, unit test files and step definition files. Use for every single generated code block this markdown code block format:
+
+```python
+# [ ] extract
+# filename: src/{filename}.py
+{python code}
+```
+
+* The extract and filename statements are only allowed once per markdown code block
+* The first character of the first line inside your code block must be '#' and the first character of the second line inside your code block must be '#'
+* replace the '# [ ] extract' statement of the template with '# [x] extract' in your response
+* in case of files get deprecated give me a list of files that can be safely deleted

ara_cli/templates/prompt-modules/commands/python_refactoring_code.commands.md

@@ -0,0 +1,39 @@
+### COMMANDS FOR REFACTORING
+
+Your job is now to refactor the code for enhancing the code quality and the design of the code according to the following guidelines:
+* Refactoring = Changing the internal structure of code
+* Without changing its external behavior
+* Goal = Improve readability, maintainability, and design
+-> "Refactoring is a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior."
+-> "Refactoring changes how code is written, not what it does."
+
+Now do:
+* Silently analyze the given code base
+* Silently analyze the given feature file (specified behavior) to fully understand the flow and logic of the current implementation. Remember: you are not allowed to change specified behavior.
+
+When you refactor the code remember:
+* The max function or method length should not exceed 40 lines.
+* The max class length should not exceed 150 lines.
+* The max file length should not exceed 150 lines.
+* Split implementation files or functions/methods/classes in case they exceed their defined length maximum.
+* Apply as coding and design principle the separation of concerns and single responsibility principle in general and specifically when you need to split.
+* Flatten nested code structures (e.g. if/while/for statements) to only one nesting level.
+* The refactored code must fully implement the specified behavior in an easy testable and modular/extensible way.
+* Follow PEP8 coding guidelines.
+* Use descriptive numpy style docstrings for inline method and class documentation.
+* Use the python logger logging package to implement logging for all application modules that enables a fine granular full observability of the program flow by the log file. Use ./logs/<module_name>.log as filepath for logging.
+
+Your output specification is:
+* Only return full copy pastable file content.
+* Use for every single generated code block this markdown code block format:
+
+```python
+# [ ] extract
+# filename: src/{filename}.py
+{python code}
+```
+
+* The extract and filename statements are only allowed once per markdown code block
+* The first character of the first line inside your code block must be '#' and the first character of the second line inside your code block must be '#'
+* replace the '# [ ] extract' statement of the template with '# [x] extract' in your response
+* in case of files get deprecated give me a list of files that can be safely deleted

ara_cli/templates/prompt-modules/commands/python_step_definitions_generation_and_fixing.commands.md

@@ -0,0 +1,40 @@
+### COMMANDS FOR CREATING AND CORRECTING STEP DEFINITIONS FOR FEATURE FILES
+
+**MANDATORY INPUT VALIDATION:**
+- Feature files (.feature) must be provided
+- Behave test report must be provided
+
+**PROMPT DEFINITION ERROR:** If mandatory input is missing, immediately stop and return: "ERROR: Missing mandatory input. Please provide both feature files (.feature) and behave test report before proceeding."
+
+**OPTIONAL INPUT:**
+- Already existing step definitions
+
+**PROMPT DEFINITION WARNING:** If optional input is missing: "WARNING: No existing step definitions provided. If step definitions already exist in your project, please include them as input context to avoid duplication and ensure consistency."
+
+### Your job is now:
+* Silently analyze the given feature files and behave test report to understand current test failures and missing step implementations.
+* Silently review any provided existing step definitions to avoid duplication and maintain consistency.
+* Develop step definition implementation strategies that minimize code changes with respect to existing step definitions, prefer reusing existing step patterns over new implementations.
+* The max function length should not exceed 25 lines. The max file length should not exceed 120 lines.
+* Always prefer to use existing python packages over your own implementation.
+* Use the behave testing framework for all step definition implementations.
+* Apply mocking extensively to isolate step definitions from external inputs and interfaces using unittest.mock or pytest-mock.
+* Fully implement all missing step definitions for the given feature files in an easy testable and modular/extensible way. Follow PEP8 coding guidelines, use numpy style docstrings for inline function documentation, apply as coding and design principle the separation of concerns and single responsibility principle.
+* Generated or reworked python methods must not exceed 25 lines of code. In case methods exceed this length they need to be split according to the single responsibility principle and separation of concerns.
+* Generated or reworked python files must not exceed 120 lines of code. In case files exceed this length they need to be split according to the single responsibility principle and separation of concerns.
+* Implement proper assertion methods that provide clear error messages when steps fail.
+* Use context.scenario, context.feature, and context.table appropriately for data sharing between steps.
+* Implement proper cleanup in @after_scenario and @after_feature hooks when necessary.
+
+* Only return full copy pastable file content for step definition files. Use for every single generated code block this markdown code block format:
+
+```python
+# [ ] extract
+# filename: ara/features/steps/{filename}_steps.py
+{python code}
+```
+
+* The extract and filename statements are only allowed once per markdown code block
+* The first character of the first line inside your code block must be '#' and the first character of the second line inside your code block must be '#'
+* replace the '# [ ] extract' statement of the template with '# [x] extract' in your response
+* in case of files get deprecated give me a list of files that can be safely deleted

ara_cli/templates/prompt-modules/commands/python_unittest_generation_and_fixing.commands.md

@@ -0,0 +1,48 @@
+### COMMANDS FOR CREATING AND CORRECTING UNIT TESTS
+
+**MANDATORY INPUT VALIDATION:**
+- Feature files (.feature) must be provided
+- Code coverage report or pytest test report must be provided
+
+**PROMPT DEFINITION ERROR:** If mandatory input is missing, immediately stop and return: "ERROR: Missing mandatory input. Please provide both feature files (.feature) and code coverage/pytest test report before proceeding."
+
+**OPTIONAL INPUT:**
+- Already existing unit tests
+
+**PROMPT DEFINITION WARNING:** If optional input is missing: "WARNING: No existing unit tests provided. If unit tests already exist in your project, please include them as input context to avoid duplication and ensure consistency."
+
+#### Your job is now:
+* Silently analyze the given feature files and code coverage/pytest test report to understand current test gaps and implementation requirements.
+* Silently review any provided existing unit tests to avoid duplication and maintain consistency with existing test patterns.
+* Develop unit test implementation strategies that minimize code changes with respect to existing tests, prefer reusing existing test patterns and fixtures over new implementations.
+* The max function length should not exceed 25 lines. The max file length should not exceed 120 lines.
+* Always prefer to use existing python packages over your own implementation.
+* Use the pytest testing framework for all unit test implementations.
+* Apply mocking extensively to isolate unit tests from external inputs and interfaces using unittest.mock or pytest-mock. Mock all external dependencies, file I/O, network calls, and database interactions.
+* Fully implement comprehensive unit tests that achieve at least 90% code coverage for the specified behavior in an easy maintainable and modular/extensible way. Follow PEP8 coding guidelines, use numpy style docstrings for inline function documentation, apply as coding and design principle the separation of concerns and single responsibility principle.
+* Generated or reworked python methods must not exceed 25 lines of code. In case methods exceed this length they need to be split according to the single responsibility principle and separation of concerns.
+* Generated or reworked python files must not exceed 120 lines of code. In case files exceed this length they need to be split according to the single responsibility principle and separation of concerns.
+
+* Implement comprehensive test cases covering:
+  - Happy path scenarios
+  - Edge cases and boundary conditions
+  - Error handling and exception scenarios
+  - Input validation scenarios
+
+* Use pytest fixtures for test data setup and teardown to ensure test isolation.
+* Implement parametrized tests using @pytest.mark.parametrize for testing multiple input combinations efficiently.
+* Use descriptive test method names that clearly indicate what is being tested.
+* Include proper assertions with meaningful error messages.
+
+* Only return full copy pastable file content for unit test files. Use for every single generated code block this markdown code block format:
+
+```python
+# [ ] extract
+# filename: test/test_{filename}.py
+{python code}
+```
+
+* The extract and filename statements are only allowed once per markdown code block
+* The first character of the first line inside your code block must be '#' and the first character of the second line inside your code block must be '#'
+* replace the '# [ ] extract' statement of the template with '# [x] extract' in your response
+* in case of files get deprecated give me a list of files that can be safely deleted

ara_cli/update_config_prompt.py

@@ -5,13 +5,13 @@ from ara_cli.prompt_handler import generate_config_prompt_template_file, generat
 
 def read_file(filepath):
     """Read and return the content of a file."""
-    with open(filepath, 'r') as file:
+    with open(filepath, 'r', encoding='utf-8') as file:
         return file.read()
 
 
 def write_file(filepath, content):
     """Write content to a file."""
-    with open(filepath, 'w') as file:
+    with open(filepath, 'w', encoding='utf-8') as file:
         file.write(content)
 
 
@@ -103,6 +103,7 @@ def handle_existing_file(file_path, tmp_file_path, generate_file_func, automatic
 
 
 def update_artefact_config_prompt_files(classifier, param, automatic_update=False):
+    from ara_cli.prompt_handler import generate_config_prompt_global_givens_file
     sub_directory = Classifier.get_sub_directory(classifier)
     artefact_data_path = os.path.join("ara", sub_directory, f"{param}.data")
     prompt_data_path = os.path.join(artefact_data_path, "prompt.data")
@@ -111,13 +112,18 @@ def update_artefact_config_prompt_files(classifier, param, automatic_update=Fals
 
     givens_file_name = "config.prompt_givens.md"
     givens_tmp_file_name = "config.prompt_givens_tmp.md"
+    global_givens_file_name = "config.prompt_global_givens.md"
+    global_givens_tmp_file_name = "config.prompt_global_givens_tmp.md"
     template_file_name = "config.prompt_templates.md"
     template_tmp_file_name = "config.prompt_templates_tmp.md"
 
     prompt_config_givens = os.path.join(prompt_data_path, givens_file_name)
     prompt_config_givens_tmp = os.path.join(prompt_data_path, givens_tmp_file_name)
+    prompt_config_global_givens = os.path.join(prompt_data_path, global_givens_file_name)
+    prompt_config_global_givens_tmp = os.path.join(prompt_data_path, global_givens_tmp_file_name)
     prompt_config_templates = os.path.join(prompt_data_path, template_file_name)
     prompt_config_templates_tmp = os.path.join(prompt_data_path, template_tmp_file_name)
 
     handle_existing_file(prompt_config_givens, prompt_config_givens_tmp, generate_config_prompt_givens_file, automatic_update)
-    handle_existing_file(prompt_config_templates, prompt_config_templates_tmp, generate_config_prompt_template_file, automatic_update)
+    handle_existing_file(prompt_config_global_givens, prompt_config_global_givens_tmp, generate_config_prompt_global_givens_file, automatic_update)
+    handle_existing_file(prompt_config_templates, prompt_config_templates_tmp, generate_config_prompt_template_file, automatic_update)

ara_cli/version.py

@@ -1,2 +1,2 @@
 # version.py
-__version__ = "0.1.9.69"   # fith parameter like .0 for local install test purposes only. official numbers should be 4 digit numbers
+__version__ = "0.1.10.8"   # fith parameter like .0 for local install test purposes only. official numbers should be 4 digit numbers

ara_cli-0.1.10.8.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: ara_cli
+Version: 0.1.10.8
+Summary: Powerful, open source command-line tool for managing, structuring and automating software development artifacts in line with Business-Driven Development (BDD) and AI-assisted processes
+Description-Content-Type: text/markdown
+Requires-Dist: langfuse
+Requires-Dist: litellm
+Requires-Dist: llama-index
+Requires-Dist: llama-index-llms-openai
+Requires-Dist: llama-index-retrievers-bm25
+Requires-Dist: openai
+Requires-Dist: markdown-it-py
+Requires-Dist: json-repair
+Requires-Dist: argparse
+Requires-Dist: argcomplete
+Requires-Dist: cmd2>=2.5
+Requires-Dist: charset-normalizer
+Requires-Dist: pydantic
+Requires-Dist: pydantic_ai
+Requires-Dist: python-docx
+Requires-Dist: pymupdf4llm
+Requires-Dist: typer
+Requires-Dist: psutil
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: requires-dist
+Dynamic: summary
+
+# ara-cli
+
+**ara-cli** is a powerful, open source command-line tool for managing, structuring and automating software development artifacts in line with Behavior-Driven Development (BDD) and AI-assisted processes. With an intuitive interface and platform-independent implementation in Python, ara-cli enables teams to structure business goals, capabilities, features, user stories, and tasks, and to leverage integrated AI/chat capabilities for requirements engineering, documentation, and process automation.
+
+---
+
+## Features
+
+- **Comprehensive Artefact Management:**  
+  Create, edit, rename, delete, and list all core artefacts of the software development lifecycle: businessgoals, vision, capabilities, keyfeatures, features, epics, userstories, examples, and tasks.
+
+- **Structured Traceability:**  
+  Organize and link artefacts for full traceability from business goals to implementation tasks. Effortlessly navigate artefact hierarchies and dependencies.
+
+- **Integrated AI and Chat:**  
+  Interact with AI language models directly from your terminal. Use chat and prompt commands to assist with documentation, requirements refinement, and artefact management.
+
+- **Prompt Templates:**  
+  Fetch, use, and manage reusable prompt templates for consistent and efficient requirements and documentation workflows.
+
+- **Artefact Status and User Management:**  
+  Assign and query status and responsible users for artefacts to support project coordination and tracking.
+
+- **Automated Quality Assurance:**  
+  Scan artefact trees for inconsistencies and automatically correct issues using integrated LLM-powered autofix functionality.
+
+- **Powerful Listing and Search:**  
+  List artefacts and filter by type, tags, content, contributor relationships, file extensions, and more.
+
+- **Open Source & Platform Independent:**  
+  Implemented in Python and available on PyPI for easy installation and integration into any workflow.
+
+---
+
+## Use Cases
+
+- **Requirements Engineering:**  
+  Capture and structure business requirements and user stories with clear traceability.
+
+- **Agile Development:**  
+  Manage and automate backlog refinement, sprint planning, and task tracking.
+
+- **AI-Enhanced Productivity:**  
+  Use chat and prompt features to accelerate documentation, code review, and knowledge management.
+
+- **Quality Management:**  
+  Ensure artefact consistency and high documentation quality via automated scans and fixes.
+
+---
+
+## Quick Start
+
+Install from PyPI:
+```bash
+pip install ara-cli
+````
+
+Create your first feature artefact:
+
+```bash
+ara create feature login
+```
+
+List all features:
+
+```bash
+ara list --include-extension .feature
+```
+
+Chat with the integrated AI:
+
+```bash
+ara chat
+```
+
+Scan and autofix artefacts:
+
+```bash
+ara scan
+ara autofix
+```
+
+---
+
+## Command Overview
+
+| Action                  | Description                                                             |
+| ----------------------- | ----------------------------------------------------------------------- |
+| create                  | Create a classified artefact with data directory                        |
+| delete                  | Delete an artefact and its data directory                               |
+| rename                  | Rename an artefact and its data directory                               |
+| list, list-tags         | List artefacts, show tags, filter by content, extension, hierarchy etc. |
+| prompt, chat            | Use AI-powered chat and prompt templates for artefact management        |
+| template                | Print artefact templates in the terminal                                |
+| fetch-templates         | Download and manage reusable prompt templates                           |
+| read                    | Output artefact contents and their full contribution chain              |
+| reconnect               | Connect artefacts to parent artefacts                                   |
+| read-status, set-status | Query and assign status to artefacts                                    |
+| read-user, set-user     | Query and assign responsible users                                      |
+| classifier-directory    | Show directory of artefact classifiers                                  |
+| scan                    | Scan the ARA tree for incompatible or inconsistent artefacts            |
+| autofix                 | Automatically correct artefact issues with LLM assistance               |
+
+See `ara -h` for the complete list of commands and usage examples.
+
+---
+## Agent Commands
+
+`ara-cli` includes powerful agent-based capabilities that can be accessed through the interactive chat. These agents can perform complex, multi-step tasks, such as conducting interviews or automating coding workflows.
+
+To use the agent commands, first start an interactive chat session:
+
+```bash
+ara prompt chat <artefact_classifier> <artefact_name>
+```
+
+Once inside the chat, you can use the following commands to manage agents:
+
+| Command          | Shortcut | Description                                       |
+| ---------------- | -------- | ------------------------------------------------- |
+| `AGENT_RUN`      | `a`      | Run an agent by name.                             |
+| `AGENT_STOP`     | `as`     | Stop the currently running agent.                 |
+| `AGENT_CONTINUE` | `ac`     | Continue the agent's operation without new input. |
+| `AGENT_STATUS`   | `astat`  | Show the status of the current agent.             |
+| `exit`           |          | Exit from agent interfacto back to chat.          |
+
+**Example:**
+
+```bash
+ara> a interview_agent
+```
+
+**Important:** The agent functionality requires the `ara-agents` package to be installed separately. If you do not have `ara-agents` installed, please contact the Talsen Team for assistance.
+
+---
+
+## Artefact Structure
+
+ara-cli organizes your project artefacts in a clear directory structure:
+
+```
+./ara/
+   ├── businessgoals/
+   ├── vision/
+   ├── capabilities/
+   ├── keyfeatures/
+   ├── features/
+   ├── epics/
+   ├── userstories/
+   ├── examples/
+   ├── tasks/
+```
+
+---
+
+## Example Workflows
+
+- **Create a new feature and link it to a user story:**
+
+```bash
+ara create feature payment contributes-to userstory checkout
+```
+
+- **Read an artefact's content and its full parent chain:**
+
+```bash
+ara read task implement_api --branch
+```
+
+- **List tasks containing specific content:**
+
+```bash
+ara list --include-extension .task --include-content "API integration"
+```
+
+- **Automate prompt-based LLM interaction for a task:**
+
+```bash
+ara prompt send task implement_api
+ara prompt extract task implement_api
+```
+
+---
+
+## Requirements
+
+- Python 3.8+
+- Platform-independent; tested on Linux, macOS, and Windows
+
+---
+
+## License
+
+This project is open source and freely available under the [MIT License](vector://vector/webapp/LICENSE).
+
+---
+
+## Links
+
+- **PyPI:** https://pypi.org/project/ara-cli/
+- **Source code:** \[GitHub link or repository URL\]
+- **Documentation:** \[Link if available\]
+
+---
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome! Please open an issue or submit a pull request via GitHub.
+
+---
+
+**ara-cli — Structure your development. Automate with AI. Build better software.**
+