### Zero Source README: Style Guide Section Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of the optional Style Guide section in a Zero Source README. ```markdown ## Style Guide Guidelines for visual design, including colors, typography, spacing, etc. ``` -------------------------------- ### Zero Source README: Project Title and Description Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of the required Project Title and Description section in a Zero Source README. ```markdown # My Project Title ## Description A concise overview of what the application does and its key benefits. ``` -------------------------------- ### Zero Source README: Technical Implementation Section Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of the Technical Implementation section in a Zero Source README, covering architecture, data structures, and algorithms. ```markdown ## Technical Implementation ### Architecture Overview of the software architecture (e.g., MVC, microservices). ### Data Structures Definitions of key data structures and their relationships. ### Algorithms Explanation of important algorithms and processes. ``` -------------------------------- ### Zero Source README: Functionality Section Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of the Functionality section in a Zero Source README, detailing core features, UI, and behavior. ```markdown ## Functionality ### Core Features - Feature 1: Description - Feature 2: Description ### User Interface Detailed description of the UI layout and components. ### Behavior Specifications Details on how the application should behave in different scenarios. ``` -------------------------------- ### README Improvement Examples Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Provides examples of how to improve README files by addressing ambiguous requirements, inconsistent terminology, and insufficient technical detail, offering problematic (❌) and improved (✅) versions. ```markdown ## Common README Issues 1. **Ambiguous Requirements** ❌ Problematic: ```markdown The app should be fast and user-friendly. ``` ✅ Improved: ```markdown The app should respond to user input within 100ms and follow Material Design guidelines for consistent UI patterns. ``` 2. **Inconsistent Terminology** ❌ Problematic: ```markdown Users can add items to their cart. ... The basket should display item quantities. ``` ✅ Improved: ```markdown Users can add items to their cart. ... The cart should display item quantities. ``` 3. **Insufficient Technical Detail** ❌ Problematic: ```markdown The app should store user data securely. ``` ✅ Improved: ```markdown The app should: - Store user data in an encrypted SQLite database - Use AES-256 encryption for sensitive data - Keep authentication tokens in secure storage - Clear sensitive data when the app goes to background ``` ``` -------------------------------- ### Generate and Run Example Application Source: https://github.com/scuffedepoch/tins/blob/main/tools/README.md Demonstrates the workflow of generating an implementation from a README and then running the generated application. This includes generating the code and setting up the project. ```bash node TINS/tools/llm-bootstrapper/index.js todo-app/README.md --output todo-app/src cd todo-app/src npm install npm start ``` -------------------------------- ### Zero Source README: Testing Scenarios Section Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of the optional Testing Scenarios section in a Zero Source README. ```markdown ## Testing Scenarios Specific test cases that the implementation should satisfy. ``` -------------------------------- ### Zero Source Metadata Tags Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of using metadata tags in a Zero Source README to provide hints to the LLM. ```markdown ``` -------------------------------- ### Example Zero Source README.md Source: https://github.com/scuffedepoch/tins/blob/main/tools/README.md An example of a structured README.md file following the Zero Source specification, including Description, Functionality, and Technical Implementation sections. ```markdown # My Todo App ## Description A simple web-based todo application that allows users to add, edit, delete, and mark tasks as complete. ## Functionality - Add new tasks with a title and optional description - Mark tasks as complete - Edit existing tasks - Delete tasks - Filter tasks by status (all, active, completed) - Persist tasks in local storage ## Technical Implementation - Frontend: HTML, CSS, JavaScript - No backend required - Local storage for data persistence - Responsive design for mobile and desktop ``` -------------------------------- ### Providing Concrete Examples for Functionality Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Illustrates how concrete examples clarify functionality requirements for AI, showing specific usage patterns versus general statements. ```markdown ✅ **Good:** The search function should support filtering by multiple criteria: - Single property: `search("name:John")` - Multiple properties: `search("name:John role:admin")` - Range values: `search("age:30-40")` ❌ **Avoid:** The search function should support filtering by properties and ranges. ``` -------------------------------- ### Generate and Run Zero Source App Locally Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Generates a Zero Source application's implementation locally and then runs it. ```bash npx @zerosource/bootstrapper ./my-app/README.md --output ./generated-app cd ./generated-app && npm start ``` -------------------------------- ### Git Version Control Workflow Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Demonstrates basic Git commands for initializing a repository, adding and committing files, and creating branches for feature development, essential for collaborative README management. ```bash # Initialize a repository git init # Add your README git add README.md # Commit changes git commit -m "Initial README for MyApp" # Create a branch for specific feature updates git checkout -b enhance-search-feature # After editing README git commit -m "Enhanced search feature description" ``` -------------------------------- ### Specific Requirements Example Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Illustrates how to replace vague requirements with specific, measurable, achievable, relevant, and time-bound (SMART) criteria for application behavior. ```markdown The application should: - Respond to user interactions within 100ms - Use consistent navigation patterns across all screens - Provide clear feedback for all actions (success, error, loading states) - Support keyboard shortcuts for common operations ``` -------------------------------- ### Zero Source README: Accessibility Requirements Section Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of the optional Accessibility Requirements section in a Zero Source README. ```markdown ## Accessibility Requirements Guidelines for ensuring the application is accessible to all users. ``` -------------------------------- ### Zero Source README: Mermaid Diagram Example Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Example of including a Mermaid diagram within a Zero Source README. ```mermaid graph TD A[Start] --> B{Is user logged in?} B -->|Yes| C[Show Dashboard] B -->|No| D[Show Login] ``` -------------------------------- ### Platform-Specific Requirements Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Details platform-specific behaviors and requirements for Web, Mobile, and Desktop environments, covering aspects like keyboard shortcuts, gestures, and system integrations. ```markdown ## Platform-Specific Behavior ### Web - Keyboard shortcuts: Ctrl+S for save - Local storage for preferences ### Mobile - Swipe gestures for navigation - Touch-optimized buttons (min 44×44px) ### Desktop - Native file system integration - System tray integration ``` -------------------------------- ### Optional README Sections Source: https://github.com/scuffedepoch/tins/blob/main/docs/specification.md Provides Markdown examples for optional but recommended sections in a Zero Source README, such as Style Guide, Testing Scenarios, Accessibility, Performance, and Extended Features. ```markdown ## Style Guide [Visual design specifications, colors, typography, animations, etc.] ## Testing Scenarios [List of test cases that the implementation should satisfy] ## Accessibility Requirements [Specifications for making the software accessible] ## Performance Goals [Metrics and targets for performance optimization] ## Extended Features [Optional features that could enhance the software] ``` -------------------------------- ### Weather Client Usage Examples Source: https://github.com/scuffedepoch/tins/blob/main/examples/api-wrapper/README.md Demonstrates how to use the weather client to fetch current weather, forecasts with different units, historical data, and geocode locations. ```javascript const weather = await weatherClient.getCurrentWeather("London,UK"); console.log(`Current temperature: ${weather.current.temperature}°C`); ``` ```javascript const forecast = await weatherClient.getForecast( { lat: 40.7128, lon: -74.0060 }, { units: "imperial" } ); forecast.forecasts.forEach(period => { console.log(`${period.time.toLocaleString()}: ${period.temperature.current}°F`); }); ``` ```javascript const historical = await weatherClient.getHistoricalWeather( { lat: 48.8566, lon: 2.3522 }, new Date('2023-01-15') ); ``` ```javascript const locations = await weatherClient.geocodeLocation("Paris"); const parisCoords = locations[0].coordinates; ``` -------------------------------- ### LLM Generation Issue Guidance Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Offers advice on how to address issues with LLM-generated implementations, focusing on providing more explicit instructions, checking for contradictions, and simplifying complex requirements. ```markdown ## LLM Generation Issues If the generated implementation doesn't match your expectations: 1. **Provide More Explicit Instructions** - Add more detail to ambiguous sections - Use examples to clarify expected behavior 2. **Check for Contradictions** - Ensure your requirements don't conflict - Maintain consistency throughout the document 3. **Simplify Complex Requirements** - Break complex features into smaller, well-defined components - Use diagrams to clarify relationships ``` -------------------------------- ### Install LLM Bootstrapper Dependencies Source: https://github.com/scuffedepoch/tins/blob/main/tools/README.md Installs the necessary dependencies for the LLM Bootstrapper tool using npm. This includes packages like commander, chalk, ora, marked, openai, and inquirer. ```bash cd TINS/tools/llm-bootstrapper npm install ``` -------------------------------- ### Code Example in README Source: https://github.com/scuffedepoch/tins/blob/main/docs/specification.md Shows an example of including a JavaScript code snippet within a Zero Source README to illustrate data structures or expected behavior. ```javascript // Example data structure { id: string, name: string, properties: { key1: value1, key2: value2 } } ``` -------------------------------- ### Defining Audience for Software Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Explains the importance of clearly stating the intended audience for the software to guide AI in implementation. ```markdown ✅ **Good:** This tool is designed for data scientists who need to visualize large datasets quickly without writing custom plotting code. ❌ **Avoid:** A data visualization tool for users to see their data. ``` -------------------------------- ### User Object Structure Example Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Defines a clear structure for a User object, including data types, constraints, and expected formats for fields like ID, username, email, role, and creation timestamp. ```javascript { id: string, // Unique identifier username: string, // Display name (3-20 characters) email: string, // Valid email address role: "user" | "admin" // User permission level created: ISO8601 date // Account creation timestamp } ``` -------------------------------- ### Validate Zero Source App Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Validates a Zero Source application's README file using the Zero Source CLI tool. ```bash npx @zerosource/bootstrapper ./my-app/README.md --validate ``` -------------------------------- ### Collaborative Editing Practices Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Outlines best practices for collaborative README editing, including using pull requests, reviewing changes, maintaining a change log, and using metadata comments for authorship tracking. ```markdown ## Collaborative Editing For collaborative editing: 1. Use pull requests to propose changes 2. Review changes carefully for consistency 3. Maintain a change log at the bottom of your README 4. Consider using metadata comments to track authorship: ```markdown ``` ``` -------------------------------- ### User Model Definition Source: https://github.com/scuffedepoch/tins/blob/main/docs/developer-guide.md Defines the structure of the User Model, including fields like id, name, email, role, and preferences. This schema is used to represent user data within the application. ```javascript { id: string, // Unique identifier name: string, // User's full name email: string, // Valid email address role: "user" | "admin", // Permission level preferences: { theme: "light" | "dark", notifications: boolean } } ``` -------------------------------- ### Balancing Detail and Clarity in Requirements Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Shows how to provide sufficient detail for AI understanding without overwhelming the reader, using numbered lists for structured requirements. ```markdown ✅ **Good:** The authentication system should: 1. Accept username/password combinations 2. Verify credentials against the database 3. Generate a JWT token with user ID and roles 4. Return the token with a 24-hour expiration ❌ **Avoid:** The system needs secure authentication with tokens. ``` -------------------------------- ### Detailing Expected Behaviors in Scenarios Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Shows how to detail expected software behaviors in various scenarios, including confirmation, data retention, and notifications. ```markdown When a user attempts to delete an account: 1. The system should prompt for confirmation 2. If confirmed, mark the account as deactivated but retain data for 30 days 3. Send a confirmation email with an option to restore the account 4. After 30 days, permanently delete all user data ``` -------------------------------- ### Comprehensive README Template Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Provides a structured template for a comprehensive project README file, covering essential sections for describing functionality, technical implementation, style, performance, accessibility, testing, and security. ```markdown # Project Title ## Description [Overall description and purpose] ## Functionality ### Core Features ### User Interface ### User Flows ### Edge Cases ## Technical Implementation ### Architecture ### Data Model ### Components ### Algorithms ### External Integrations ## Style Guide ### Visual Design ### Interactions ### Responsive Behavior ## Performance Requirements [Performance targets and optimization strategies] ## Accessibility Requirements [Accessibility standards and implementations] ## Testing Scenarios [Test cases covering critical functionality] ## Security Considerations [Security requirements and potential vulnerabilities] ``` -------------------------------- ### Highlighting Key Differentiators Source: https://github.com/scuffedepoch/tins/blob/main/docs/best-practices.md Provides guidance on explaining unique features of the software to AI, differentiating it from alternatives. ```markdown ✅ **Good:** Unlike traditional task managers, this application uses natural language processing to automatically categorize and prioritize tasks based on their content and context. ``` -------------------------------- ### LLM Bootstrapper CLI Options Source: https://github.com/scuffedepoch/tins/blob/main/tools/README.md Lists and describes the available command-line options for the LLM Bootstrapper tool, allowing users to customize the code generation process. ```APIDOC LLM Bootstrapper CLI Options: --output, -o Specify output directory for generated code. --model, -m Specify LLM model to use (default: gpt-4). --verbose, -v Show detailed generation process. --validate Only validate the README, don't generate code. --interactive Run in interactive mode with step-by-step guidance. --lang Specify preferred programming language. --platform Specify target platform (web, mobile, desktop). --template