# System Patterns

## Architecture
- Static website generated by 11ty.
- Content is sourced from Markdown files organized within discipline-specific directories.
- Hosted directly via GitHub Pages.

## Content Organization
- **Top-level:** Disciplines (e.g., `development/`, `project-management/`, `sales-marketing/`, `content-strategy/`, `design`, `quality-assurance`)
- **Second-level:** Content Types (`prompts/`, `rules/`, `project-configs/`, `workflow-states/`)
- Specific content items are individual Markdown files within these directories, typically using `kebab-case.md` naming.
- An `index.njk` file often exists within discipline directories (e.g., `development/index.njk`) and content-type directories (e.g., `development/prompts/index.njk`) likely serving as landing/listing pages.
- 11ty collections are automatically generated for each content type, aggregating across disciplines.
- **IMPORTANT:** The list of disciplines in `.eleventy.js` (`const disciplines = [...]`) must always include all actual discipline folders. If a discipline is missing from this array, its content will not appear in collections, the homepage, or navigation. This caused the Quality Assurance section to be invisible until fixed.

## Templating
- Nunjucks (.njk) is used as the primary templating engine (for md, html, data files).
- Key layout files:
    - `_layouts/base.njk`
    - `_layouts/discipline.njk`
    - `_layouts/content-type.njk`
- Includes/partials are stored in `_includes/`.
- Global data is stored in `_data/`.
- Custom Nunjucks filters defined in `.eleventy.js`: `date`, `filterByDiscipline`, `fullUrl`, `hasContent`.
- Directory structure configured in `.eleventy.js`: input (`.`), output (`_site`), includes (`_includes`), layouts (`_layouts`), data (`_data`).

## Search
- A search index (`search-index.json`) is generated during build containing title, description, content, url, discipline, contentType, tags, and date for all `.md` files.
- Search functionality is implemented client-side via JavaScript in `_includes/search.njk`.
- **Implementation:**
    - Fetches `search-index.json` on page load.
    - Filters the index in the browser based on user input (case-insensitive matching on title, description, content, tags).
    - Results displayed dynamically, updating as user types (min 2 chars).
- **Features:**
    - Results link to the content page.
    - "View Prompt" button on each result opens a modal displaying the full Markdown content rendered using `marked.parse()` (requires `marked.js` library).
- Styling for search components and modal is included within `_includes/search.njk`.

## Styling & Assets
- Static assets (CSS, JS, Images) are located in the `assets/` directory and copied directly to `_site/assets` during build.

## CI/CD
- GitHub Actions workflow defined in `.github/workflows/deploy.yml`.
- **Trigger:** Runs on push to `main` branch and `workflow_dispatch`.
- **Environment:** `ubuntu-latest` with Node.js v22.
- **Process:**
    1. Checkout code.
    2. Setup Node.js & cache npm dependencies.
    3. Install dependencies (`npm install`).
    4. Build site (`npm run build`) - output to `./_site`.
    5. Deploy `./_site` contents to `gh-pages` branch using `peaceiris/actions-gh-pages@v4`.
- The build process adapts URLs based on `process.env.GITHUB_ACTIONS` (adds `/prompt_library` base path), configured in `.eleventy.js`.
- A `baseUrl` global variable and `pathPrefix` are configured in `.eleventy.js` to handle deployment to GitHub Pages subpath.

## Contribution Process
- Contribution guidelines are documented in the `contributing.njk` page.
- **Methods:**
    - **GitHub Direct:** Standard Fork -> Branch -> Add File -> Commit -> PR workflow.
    - **Cursor:** Recommends using Cursor AI with the `prompt-library-requirements` rule for guided content creation.
    - **GitHub Issues:** Allows users to suggest content via issues tagged "Content Suggestion:".
- **Content Requirements:**
    - **Metadata (Frontmatter):** `title`, `description`, `date`, `tags` (min 2).
    - **Formatting:** Markdown, clear headings, code blocks, reasonable line length, lists.
    - **Validation:** Check metadata, preview locally (`npm start`), validate links/code, check style.
- The `contributing.njk` page includes an accordion UI (JS/CSS) to present the methods.

### Planned Contribution Workflow (via Issue Templates)
- **Initiation:** Contributor selects an Issue Template (e.g., for prompts) and fills out the form.
- **Submission:** A GitHub Issue is created with structured data and specific labels (e.g., `new-contribution`, `needs-review`).
- **Curation:** Maintainer reviews the issue, verifies the content, and potentially refines the data (e.g., adds tags).
- **Conversion:** Maintainer manually creates the corresponding Markdown file in the correct location, populating the frontmatter and content from the issue data.
- **Integration:** Maintainer commits the new file, typically via a PR, for final review and merge.

### Slack Prompt Submission Workflow (via GitHub Actions)
- **Initiation:** A Slack bot sends a `repository_dispatch` event (`type: slack-prompt-submission`) to the GitHub API for this repository.
- **Payload:** The event's `client_payload` contains the prompt content, author, invoker, permalink, and a shared secret.
- **Trigger:** The dispatch event triggers the `.github/workflows/slack_submit.yml` workflow.
- **Validation:** The workflow validates the shared secret against a repository secret (`secrets.SLACK_SHARED_SECRET`) and checks for required fields in the payload.
- **Issue Creation:** If validation passes, the workflow uses the GitHub API (via `gh` CLI with `GITHUB_TOKEN`) to create a new issue in this repository, formatted with the content and metadata from the payload.
- **Labels:** The issue is automatically labeled (e.g., `new-prompt`, `from-slack`).
- **Response Limitation:** The workflow trigger (`repository_dispatch`) does not return a custom response body to the caller (Slack bot). The bot only receives confirmation that the event was dispatched (HTTP 204), not that the issue was successfully created.
- **Maintainer Action:** This issue follows the same curation and conversion process as issues created via templates. 

## Section Initialization Pattern
- All discipline/content-type folders (e.g., `quality-assurance/prompts/`, `quality-assurance/rules/`, etc.) should be initialized with a customized `index.njk` file containing relevant metadata (title, description, layout, discipline, contentType, category) and placeholder content describing the section's purpose.
- This replaces the use of `.gitkeep` files for empty folder tracking, ensuring each section is ready for content and discoverable in the UI.
- This pattern was applied to the Quality Assurance section, with each subfolder now containing a Quality Assurance-specific `index.njk` file.