Add comprehensive instructions and module index (#33)

* feat(instructions): add comprehensive instructions modules

* feat(modules): add comprehensive module index

Introduces a new README.md file in the instructions-modules directory that serves as a complete, categorized index of all available instruction modules. This provides a single source of truth for browsing and discovering modules.

The module authoring guide and module system documentation have been updated to link to this new index, improving discoverability and helping to prevent the creation of redundant modules.

* docs(instructions-modules): expand README with module description

Added detailed descriptions to each module in the README for clarity and usability.

Author: synthable

docs/module_authoring_guide.md

@@ -1,6 +1,6 @@
 # Module Authoring & Development Guide
 
-- [Module Authoring \& Development Guide](#module-authoring--development-guide)
+- [Module Authoring & Development Guide](#module-authoring--development-guide)
   - [1. Introduction](#1-introduction)
   - [2. Module Structure](#2-module-structure)
     - [2.1. YAML Frontmatter](#21-yaml-frontmatter)
@@ -128,7 +128,7 @@ Follow this systematic process to create new, high-quality modules. This workflo
 
 ### Step 1: Deconstruct the Concept
 
-- Identify the Core Concept: What is the single, atomic idea this module will represent?
+- Identify the Core Concept: What is the single, atomic idea this module will represent? Before you begin, review the [existing module library](../instructions-modules/README.md:1) to ensure your concept is not redundant.
 - Formulate the Primary Directive: What is the one command it gives the AI?
 - Outline the Process: What are the logical steps to achieve this directive?
 - Define the Constraints: How could this rule be misinterpreted? What are the explicit anti-patterns to forbid?

docs/module_system.md

@@ -33,6 +33,8 @@ A module should be:
 
 This principle means we use specific, descriptive filenames (e.g., `deductive-reasoning.md`) and strictly avoid generic "bucket" files (e.g., `basics.md`). The module file system is a **library of specific concepts**, and the persona file is the **composition tool** used to assemble them.
 
+A complete, categorized list of all available modules can be found in the [`instructions-modules/README.md`](../instructions-modules/README.md:1) file.
+
 ## 3. The Grand Architecture: The Four-Tier System
 
 The module system is organized into a four-tier hierarchy. This structure creates a "waterfall of abstraction," guiding the AI from the most universal rules of thought down to the most concrete actions. For maximum effectiveness, personas should always be assembled in the `Foundation -> Principle -> Technology -> Execution` order.

instructions-modules/README.md

@@ -0,0 +1,32 @@
+---
+name: 'Playbook: Verify and Comment Documentation'
+description: 'A step-by-step process for auditing documentation against a codebase.'
+---
+
+## Primary Directive
+
+Audit project's documentation file(s) against its codebase and comment out any hallucinated features.
+
+## Process
+
+1. **Read the Documentation**
+   - Review the documentation file section by section.
+
+2. **Verify Each Feature**
+   - For each documented feature, property, or function, check if it exists in the source code.
+
+3. **Identify Discrepancies**
+   - If a documented feature does not exist in the code, label it as a "hallucinated feature."
+
+4. **Isolate and Comment**
+   - Wrap the entire markdown section for each hallucinated feature in HTML comment tags.
+   - The comment must start with `<!-- HALLUCINATION:` and end with `-->`.
+
+5. **Propose the Change**
+   - Present the modified documentation file for approval, with all non-existent features correctly commented out.
+
+## Constraints
+
+- You MUST ONLY wrap hallucinated features in `<!-- HALLUCINATION: ... -->` comment blocks.
+- You MUST NOT modify or comment out features that exist in the codebase.
+- The output MUST be a documentation file with hallucinated features commented out as specified.

instructions-modules/execution/playbook/audit-documentation/verify-and-comment.md

@@ -0,0 +1,41 @@
+---
+name: 'Debug an Issue'
+description: 'A systematic playbook for debugging, leveraging foundational modules like root-cause-analysis and causal-reasoning.'
+tags:
+  - execution
+  - playbook
+  - debugging
+  - root-cause-analysis
+---
+
+# Playbook: Debug an Issue
+
+## Primary Directive
+
+You MUST follow a systematic process to identify, understand, and resolve the root cause of a bug, not just its symptoms.
+
+## Process
+
+1.  **Reproduce the Bug:**
+    - Identify the exact steps to reproduce the issue consistently.
+    - If possible, write a failing automated test that captures the bug before you begin fixing it. This test will serve as your validation.
+2.  **Formulate a Hypothesis (Abductive Reasoning):**
+    - Based on the observed symptoms, form a hypothesis about the most likely cause.
+    - Ask: "What is the simplest explanation for why this is failing?"
+3.  **Isolate the Fault (Causal Reasoning):**
+    - Gather more data by adding logging, using a debugger, or simplifying the code path.
+    - Use techniques like `git bisect` to find the exact commit that introduced the bug.
+    - Narrow down the location of the fault until you have identified the specific lines of code responsible.
+4.  **Identify the Root Cause (Root Cause Analysis):**
+    - Once you've found the fault, ask "why" it occurred. Was it a typo? A flawed logical assumption? A misunderstanding of an API?
+    - Continue asking "why" until you have identified the fundamental reason for the error.
+5.  **Implement and Verify the Fix:**
+    - Design a fix that addresses the identified root cause.
+    - If you wrote a failing test in step 1, ensure your fix makes it pass. If not, write a test now.
+    - Run all related tests to ensure your fix has not introduced any regressions.
+
+## Constraints
+
+- Do NOT fix only the symptom. A fix MUST address the root cause.
+- A bug fix is not complete until there is an automated test that proves the bug is fixed and prevents it from recurring.
+- Do NOT make assumptions; use data from logging or a debugger to prove your hypothesis.

instructions-modules/execution/playbook/debug-issue.md

@@ -0,0 +1,29 @@
+---
+name: 'Design Microservices Architecture'
+description: 'A playbook for designing a system based on the microservices architectural style.'
+tags:
+  - architecture
+  - microservices
+  - playbook
+  - design
+---
+
+# Design Microservices Architecture
+
+## Primary Directive
+
+Given a set of business requirements, you MUST generate a high-level design for a microservices architecture that adheres to the principles of loose coupling and high cohesion.
+
+## Process
+
+1.  **Identify Bounded Contexts:** Analyze the requirements using Domain-Driven Design principles to identify the core business domains. These will form the boundaries of your microservices.
+2.  **Define Service APIs:** For each identified service, define its public API contract. Specify the commands it accepts, the queries it answers, and the events it emits.
+3.  **Plan Data Ownership:** Each service MUST own its own data. Define the data schema for each service and explicitly forbid direct database access between services.
+4.  **Select Communication Patterns:** Propose a communication strategy. Use synchronous APIs (e.g., REST, gRPC) for queries and commands that require an immediate response. Use asynchronous events (e.g., via a message queue) for notifications and to decouple services.
+5.  **Address Cross-Cutting Concerns:** Outline a strategy for handling cross-cutting concerns like service discovery, configuration management, authentication/authorization, and distributed tracing.
+
+## Constraints
+
+- The proposed design MUST avoid creating a "distributed monolith" where services are chatty and tightly coupled.
+- The number of services should be justified; do not decompose the system more than necessary.
+- The design MUST include a plan for observability (logging, metrics, tracing) from day one.

instructions-modules/execution/playbook/design-microservices-architecture.md

@@ -0,0 +1,38 @@
+---
+name: 'Document a Function'
+description: 'A playbook for writing comprehensive documentation for a given function, including its parameters, return value, and potential errors.'
+tags:
+  - execution
+  - playbook
+  - documentation
+  - functions
+---
+
+# Playbook: Document a Function
+
+## Primary Directive
+
+You MUST generate comprehensive and clearly-structured documentation for any given function, following a standard format that covers its purpose, parameters, return value, and potential errors.
+
+## Process
+
+1.  **Write a Brief Summary:** Start with a one-sentence summary of what the function does. This should be clear and concise.
+2.  **Describe Parameters:**
+    - List each parameter on a new line.
+    - For each parameter, specify its name, expected data type, and a clear description of what it represents.
+    - Indicate if the parameter is optional and what its default value is.
+3.  **Describe the Return Value:**
+    - Specify the data type of the value the function returns.
+    - Describe what the returned value represents.
+    - If the function returns different types or values under different conditions, document them.
+4.  **Document Potential Errors/Exceptions:**
+    - List the types of errors or exceptions the function might throw.
+    - For each error, describe the conditions under which it would occur.
+5.  **Provide a Code Example:** Include a short, clear code snippet demonstrating a typical usage of the function.
+
+## Constraints
+
+- The documentation MUST be written in a format compatible with standard documentation generators for the target language (e.g., JSDoc, TSDoc, Python Docstrings).
+- Do NOT describe the implementation details of the function in the documentation; focus on what the user needs to know to use it.
+- Every parameter and the return value MUST be documented.
+- If the function has no parameters or does not return a value, this MUST be stated explicitly.

instructions-modules/execution/playbook/document-a-function.md

@@ -0,0 +1,32 @@
+---
+name: 'Generate New Instruction Module'
+description: "A playbook that orchestrates the creation of a new, well-structured instruction module based on a user's request."
+tags:
+  - workflow
+  - playbook
+  - generate
+  - create
+  - module author
+---
+
+# Generate New Instruction Module
+
+## Primary Directive
+
+You will generate a complete, well-structured, and machine-centric instruction module based on the user's provided concept.
+
+## Process
+
+1.  **Acknowledge and Deconstruct:** Acknowledge the user's request. Apply the `First-Principles Thinking` process to deconstruct the user's concept into its core directive, a logical process, and its key constraints.
+2.  **Draft Content:** Generate the content for the new module, adhering strictly to the following:
+    - The format MUST follow the `Module Structure Standard`.
+    - The language MUST follow the `Machine-Centric Language` style guide.
+3.  **Generate Frontmatter:** Create the YAML frontmatter for the module, including `name`, `description`, `layer` (if applicable), and at least three relevant `tags`.
+4.  **Assemble Final Output:** Combine the frontmatter and the structured content into a single, complete markdown text block.
+5.  **Present for Review:** Output the final, complete module content. Your task is complete upon presenting the generated module.
+
+## Constraints
+
+- You MUST generate the content yourself based on your understanding of the concept. Do not ask the user to provide the content for the sections.
+- Do not invent concepts or directives not implied by the user's request. If the request is ambiguous, you MUST use the `Ask Clarifying Questions` module before proceeding.
+- Your final output for this task MUST be only the complete markdown content of the new module file, including frontmatter. Do not wrap it in conversational text.

instructions-modules/execution/playbook/generate-new-instruction-module.md

@@ -0,0 +1,27 @@
+---
+name: 'Generate New Persona Module'
+description: "A playbook for generating a new, complete persona file from a user's concept."
+---
+
+## Primary Directive
+
+You MUST generate a complete, well-structured persona file based on the user's provided concept.
+
+## Process
+
+1.  **Acknowledge and Deconstruct:** Acknowledge the user's request. Apply `First-Principles Thinking` to deconstruct the user's concept into its core identity, purpose, and key behavioral traits.
+2.  **Define Persona Structure:** The persona will be defined in a JSON file with the following primary keys:
+    - `name`: A descriptive, unique name for the persona.
+    - `description`: A concise, one-sentence summary of the persona's purpose.
+    - `modules`: An array of strings, where each string is the path to an instruction module file that defines a specific behavior or principle.
+    - `tags`: An array of relevant keywords.
+3.  **Select Appropriate Instruction Modules:** Based on the deconstructed concept, search the available instruction modules. Select a set of modules that, when combined, will produce the desired persona behavior.
+4.  **Assemble the Persona JSON:** Construct the final JSON object. Populate the `name`, `description`, and `tags`. For the `modules` array, add the file paths of all selected modules.
+5.  **Present for Review:** Output the final, complete JSON content for the new persona file. Your task is complete upon presenting the generated file.
+
+## Constraints
+
+- You MUST generate the content yourself based on your understanding of the concept. Do not ask the user to provide the content for the JSON file.
+- Do not invent concepts or behaviors not implied by the user's request.
+- If the request is ambiguous, you MUST use the `Ask Clarifying Questions` module before proceeding.
+- Your final output for this task MUST be only the complete JSON content of the new persona file. Do not wrap it in conversational text.

instructions-modules/execution/playbook/generate-new-persona-module.md

@@ -0,0 +1,33 @@
+---
+name: 'Lint Persona File'
+description: "A playbook to analyze a persona's module list and generate a comprehensive quality and consistency report."
+tags:
+  - lint
+  - validation
+  - report
+  - playbook
+---
+
+# Lint Persona File
+
+## Primary Directive
+
+You MUST analyze the provided list of module IDs and generate a structured report detailing any violations of architectural best practices, potential conflicts, or structural inconsistencies.
+
+## Process
+
+1.  **Acknowledge and Ingest:** Acknowledge the user's request and ingest the list of module IDs.
+2.  **Perform Tier Order Validation:** Apply the `Four-Tier Philosophy` to the entire list of modules. Record any violations.
+3.  **Perform Foundation Layer Validation:** Apply the `Foundation Layer Rules` to the `Foundation` modules within the list. Record any violations.
+4.  **Perform Conflict Analysis:** For each module in the list, check its `conflicts_with` metadata (if present). Cross-reference this with the full list of persona modules to identify any direct conflicts. Record any findings.
+5.  **Synthesize Report:** Generate a final report in Markdown format. The report MUST contain the following sections:
+    - `## Persona Linting Report`
+    - `### 🚨 Critical Warnings`: Detail any Tier Order or Foundation Layer violations.
+    - `### ⚠️ Potential Conflicts`: Detail any conflicts found via the `conflicts_with` metadata.
+    - `### ✅ Analysis Complete`: A concluding statement.
+
+## Constraints
+
+- Your analysis MUST be objective and based only on the rules defined in your loaded modules.
+- If no issues are found, the report should state "No issues found." under each section.
+- Your final output MUST be only the structured report.