Feat/module schema (#35)

* feat(build, validate): Add verbose output option for commands

- Implemented verbose logging for the build and validate commands.
- Updated handleBuild and handleValidate functions to accept verbose option.
- Enhanced user feedback during file validation and persona building processes.

* refactor(build, validate): Move validation functions to persona-service

- Moved validatePersona and validatePersonaFile functions to a new persona-service module for better organization.
- Updated imports in build and validate commands to reflect the new structure.
- Improved separation of concerns by isolating persona validation logic.

* test(error-handler): Add unit tests for handleError function

- Verify error handling with provided spinner
- Ensure console logging when no spinner is present
- Handle non-Error objects gracefully
- Confirm no logging for non-Error instances

* test(build): Add unit tests for handleBuild function

* test(create-module): Add unit tests for handleCreateModule function

- Mock file system and ora dependencies
- Test successful module creation
- Handle existing module file scenario
- Validate default layer usage for recognized subjects
- Ensure exit on missing layer for foundation tier
- Check for invalid layer values
- Handle file system errors during creation

* test(create-persona): Add unit tests for handleCreatePersona function

* test(module-service): Add unit tests for module validation functions

- Implement tests for validateFrontmatter, validateModuleSchema, validateModuleFile, and scanModules functions.
- Ensure coverage for valid and invalid scenarios, including required fields and error handling.

* test(persona-service): Add unit tests for persona validation

* test(validate): Add unit tests for handleValidate function

- Implement tests for validating module and persona files
- Handle scenarios for no files found and unsupported file types
- Mock dependencies for consistent test results

* test(validate): Add unit tests for module validation

* refactor(module-service): Simplify module validation logic and improve structure

- Consolidate module validation into a single function
- Remove redundant parsing functions
- Enhance error handling for module content validation
- Update tests to reflect changes in validation logic

* refactor(build): Enhance module validation and output assembly

* chore(instructions): add layer null to various module files

* refactor(instructions): Remove 'layer: null' from execution/persona-builder modules

* refactor(instructions): Remove 'layer: null' from various modules

* chore(instructions): update various modules to include 'layer: null'

* refactor(instructions): add tier to modules

Author: synthable

instructions-modules/execution/persona-builder/foundation-layer-rules.md

@@ -0,0 +1,31 @@
+---
+tier: execution
+name: 'Foundation Layer Rules'
+description: "The rule that Foundation modules must be ordered by their 'layer' metadata, from lowest to highest."
+tags:
+  - foundation
+  - layer
+  - validation
+  - ordering
+layer: null
+---
+
+# Foundation Layer Rules
+
+## Primary Directive
+
+Within the block of `Foundation` modules in a persona, you MUST validate that the modules are ordered by their `layer` property in ascending order.
+
+## Process
+
+1.  **Isolate Foundation Block:** Identify all consecutive `Foundation` modules in the persona's list.
+2.  **Track Maximum Layer:** Initialize a `max_layer_seen` variable to -1.
+3.  **Iterate and Compare:** For each `Foundation` module in the block:
+    a. Read its `layer` value from its metadata.
+    b. If the module's `layer` is LESS THAN `max_layer_seen`, you MUST flag it as a Foundational Layer Violation.
+    c. Otherwise, update `max_layer_seen` to the current module's `layer` if it is higher.
+
+## Constraints
+
+- This rule only applies to modules within the `Foundation` tier.
+- It is valid for modules to have the same layer number (e.g., two `layer: 1` modules in a row). The violation only occurs when a lower layer appears after a higher one.

instructions-modules/execution/persona-builder/four-tier-philosophy.md

@@ -0,0 +1,32 @@
+---
+tier: execution
+name: 'Four-Tier Philosophy'
+description: 'The mandatory hierarchical order for persona module tiers: Foundation -> Principle -> Technology -> Execution.'
+tags:
+  - architecture
+  - validation
+  - ordering
+  - tiers
+layer: null
+---
+
+# Four-Tier Philosophy
+
+## Primary Directive
+
+You MUST validate that the modules in a given persona file follow the strict hierarchical order: `Foundation` modules first, followed by `Principle`, then `Technology`, and finally `Execution`.
+
+## Process
+
+1.  **Scan and Categorize:** Ingest the ordered list of module IDs. For each ID, determine its tier from its path.
+2.  **Track Tier State:** Iterate through the list, keeping track of the current tier. The allowed state transitions are:
+    - `Foundation` -> `Principle`
+    - `Principle` -> `Technology`
+    - `Technology` -> `Execution`
+3.  **Detect Violations:** If you encounter a module from a tier that violates the allowed state transition (e.g., a `Technology` module appearing after an `Execution` module), you MUST flag it as a Tier Order Violation.
+
+## Constraints
+
+- A persona is not required to contain modules from all four tiers.
+- It is valid for a tier to be skipped (e.g., `Foundation` -> `Technology`). The order of the present tiers must be respected.
+- Multiple modules from the same tier can appear consecutively. The violation only occurs when a lower tier appears after a higher tier.

instructions-modules/execution/persona-builder/machine-centric-language.md

@@ -0,0 +1,40 @@
+---
+tier: execution
+name: 'Machine-Centric Language'
+description: 'A style guide for using imperative, unambiguous, and direct language suitable for programming an AI.'
+tags:
+  - language
+  - style guide
+  - imperative
+  - unambiguous
+  - prompt engineering
+  - clarity
+layer: null
+---
+
+# Machine-Centric Language
+
+## Primary Directive
+
+All generated module content MUST be written in imperative, unambiguous, and machine-interpretable language. The module is a configuration file, not a tutorial.
+
+## Process
+
+1.  **Use Modal Verbs of Obligation:** All directives MUST use words like "MUST," "WILL," "SHALL."
+    - _Correct:_ "You MUST validate the input."
+    - _Incorrect:_ "You should validate the input."
+2.  **Use Active Voice:** The AI is the subject performing the action.
+    - _Correct:_ "You WILL analyze the data."
+    - _Incorrect:_ "The data will be analyzed."
+3.  **Be Specific and Quantifiable:** Replace vague terms with precise instructions.
+    - _Correct:_ "If cyclomatic complexity is greater than 10, you MUST refactor."
+    - _Incorrect:_ "If the code is too complex, you should refactor."
+4.  **Define All Terms:** Do not assume the AI will infer the correct meaning of a specialized term within the context of the module.
+    - _Correct:_ "Apply the '5 Whys' technique, where you recursively ask 'Why?' to trace a symptom to its root cause."
+    - _Incorrect:_ "Do a root cause analysis."
+
+## Constraints
+
+- Do NOT use conversational filler, rhetorical questions, or explanatory prose.
+- Do NOT use hedging language (e.g., "maybe," "perhaps," "it seems like").
+- Do NOT use analogies or metaphors to explain a concept; instead, define the process algorithmically.

instructions-modules/execution/persona-builder/module-structure-standard.md

@@ -0,0 +1,32 @@
+---
+tier: execution
+name: 'Module Structure Standard'
+description: 'The mandatory three-section format for all instruction modules.'
+tags:
+  - format
+  - template
+  - structure
+  - standard
+  - directive
+  - process
+  - constraints
+layer: null
+---
+
+# Module Structure Standard
+
+## Primary Directive
+
+All generated instruction module content MUST strictly adhere to the following three-section format, using Markdown H2 level (`##`) for each heading.
+
+## Process
+
+1.  **`## Primary Directive` Section:** This section MUST contain a single, concise, imperative sentence that defines the module's core, non-negotiable command.
+2.  **`## Process` Section:** This section MUST contain an ordered, step-by-step list (`1.`, `2.`, `3.`) that defines the algorithm or workflow the AI must follow to comply with the Primary Directive.
+3.  **`## Constraints` Section:** This section MUST contain a bulleted list (`-`) of negative constraints, anti-patterns, or explicit boundaries. It defines what the AI MUST NOT do.
+
+## Constraints
+
+- Do not add any additional top-level `##` headings beyond the three specified.
+- Do not omit any of the three required sections.
+- You MUST use the exact heading names: `Primary Directive`, `Process`, and `Constraints`.

instructions-modules/execution/persona-builder/validation-rules.md

@@ -0,0 +1,43 @@
+---
+tier: execution
+name: 'Instruction Module Validation Rules'
+description: 'A set of strict validation rules to ensure that every instruction module is high-quality, well-structured, and machine-interpretable.'
+tags:
+  - persona-builder
+  - validation
+  - quality
+  - meta
+layer: null
+---
+
+# Instruction Module Validation Rules
+
+## Primary Directive
+
+All instruction modules MUST pass a systematic validation process to ensure they are well-formed, clear, and adhere to the established standard before being integrated into a persona.
+
+## Process
+
+1.  **Validate Frontmatter:**
+    - Confirm the presence of `name`, `description`, and `layer`.
+    - The `name` MUST be descriptive and use Title Case.
+    - The `description` MUST be a single, concise sentence explaining the module's purpose.
+    - The `layer` MUST be an integer or `null`.
+2.  **Validate Structure:**
+    - The module MUST contain exactly three H2 headings: `## Primary Directive`, `## Process`, and `## Constraints`.
+    - The content under `Process` MUST be a numbered list (`1.`, `2.`, etc.).
+    - The content under `Constraints` MUST be a bulleted list (`-`).
+3.  **Validate Content:**
+    - **Primary Directive:** It MUST be a single, imperative sentence. It MUST contain a modal verb of obligation (e.g., "MUST," "MUST NOT").
+    - **Process:** Each step MUST describe an action. The steps should be logical and sequential.
+    - **Constraints:** Each item MUST clearly define a boundary or a negative command, typically starting with "Do NOT," "MUST NOT," or similar phrasing.
+4.  **Validate Language:**
+    - The language MUST be clear, direct, and unambiguous, intended for machine interpretation.
+    - The module MUST adhere to the principles defined in `Clean Code Principles` metaphorically (e.g., single responsibility, clarity).
+    - The module MUST NOT contain placeholder text like "[Add details here]".
+
+## Constraints
+
+- A module that fails any validation check MUST NOT be used or integrated.
+- Validation is not optional; it is a required step in the module authoring workflow.
+- The rules defined in this module apply to all other instruction modules, including this one.

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

@@ -1,6 +1,8 @@
 ---
+tier: execution
 name: 'Playbook: Verify and Comment Documentation'
 description: 'A step-by-step process for auditing documentation against a codebase.'
+layer: null
 ---
 
 ### Execution Playbook: Audit and Correct Documentation

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

@@ -1,6 +1,8 @@
 ---
+tier: execution
 name: 'Playbook: Verify and Comment Documentation'
 description: 'A step-by-step process for auditing documentation against a codebase.'
+layer: null
 ---
 
 ## Primary Directive

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

@@ -1,11 +1,13 @@
 ---
+tier: execution
 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
+layer: null
 ---
 
 # Playbook: Debug an Issue

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

@@ -1,11 +1,13 @@
 ---
+tier: execution
 name: 'Design Microservices Architecture'
 description: 'A playbook for designing a system based on the microservices architectural style.'
 tags:
   - architecture
   - microservices
   - playbook
   - design
+layer: null
 ---
 
 # Design Microservices Architecture

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

@@ -1,11 +1,13 @@
 ---
+tier: execution
 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
+layer: null
 ---
 
 # Playbook: Document a Function