description: AI rules derived by SpecStory from the project AI interaction history globs: \*

description: AI rules derived by SpecStory from the project AI interaction history globs: *

PROJECT OVERVIEW

CODE STYLE

FOLDER ORGANIZATION

TECH STACK

PROJECT-SPECIFIC STANDARDS

WORKFLOW & RELEASE RULES

REFERENCE EXAMPLES

PROJECT DOCUMENTATION & CONTEXT SYSTEM

DEBUGGING

Git Commit Issues:
- If commits are blocked due to pre-commit hook failures, especially with
```
mypy
```
  , check for issues related to the
```
types-all
```
  dependency in
```
.pre-commit-config-rapid.yaml
```
  .
- The
```
mypy
```
  hook may fail if it tries to install
```
types-all
```
  , which depends on a yanked/nonexistent stub package (
```
types-pkg-resources
```
  ).
- To resolve:
  - Remove or narrow the
```
types-all
```
    dependency in
```
.pre-commit-config-rapid.yaml
```
    under the
```
mypy
```
    hook. For example, delete
```
additional_dependencies: [types-all]
```
    or replace it with only the stubs you actually need (e.g.,
```
types-requests
```
    , etc.).
  - Run
```
pre-commit clean && pre-commit install
```
    (or just retry the commit; pre-commit will reinstall environments).
  - Optional: run
```
pre-commit autoupdate
```
    to pull newer hook revisions, but the main issue is
```
types-all
```
    .
- After resolving the
```
types-all
```
  issue, refresh the pre-commit environments and reinstall the hooks using:
```
pre-commit clean && pre-commit install
```
  . Then, retry the commit.

Pre-commit Hook Failures:

When pre-commit hooks fail, address the issues systematically:
1. Shell Scripts: Ensure shell scripts have executable permissions (
```
chmod +x script_name.py
```
  ).
2. YAML Formatting: Check
```
.bandit
```
  for YAML syntax errors.
3. Markdown Formatting: Use
```
mdformat
```
  to fix markdown issues.
4. Python Linting: Resolve
```
flake8
```
  and
```
mypy
```
  errors.
5. Shell Linting: Address
```
shellcheck
```
  issues.
6. Configuration Issues: Resolve issues reported by
```
bandit
```
  and
```
detect-secrets
```
  .
For
```
detect-secrets
```
issues, try running
```
pre-commit autoupdate
```
.

If ESLint reports missing configuration, create an

.eslintrc.json

file. Example:

{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": "eslint:recommended",
  "parserOptions": {
    "ecmaVersion": 12,
    "sourceType": "module"
  },
  "rules": {}
}

To auto-fix formatting issues, stage all changes (
```
git add -u
```
) before committing.
If pre-commit hooks are causing persistent issues, temporarily bypass them using
```
git commit --no-verify -m "chore: fix pre-commit hook configuration issues"
```
(use with caution).

Comprehensive Pre-commit Troubleshooting:

If facing multiple pre-commit failures, follow these steps:

Identify the Issues: Carefully examine the pre-commit output to pinpoint the specific errors. These often include:
- YAML syntax errors (e.g., in
```
.bandit
```
  or
```
.pre-commit-config-rapid.yaml
```
  )
- Markdown formatting problems.
- Python linting errors (flake8, mypy).
- Shell script permission issues.
- Configuration problems flagged by bandit or detect-secrets.

Address Shell Script Permissions: Use

chmod +x script_name.py

to grant execute permissions to the relevant scripts. Example:

chmod +x automation/scripts/ecosystem_visualizer.py
chmod +x automation/scripts/update_agent_docs.py
chmod +x automation/scripts/mouthpiece_filter.py
chmod +x project_meta/context-handoff/context_generator.py

Update pre-commit hooks: Run
```
pre-commit autoupdate
```
to update
```
detect-secrets
```
and other hooks.

Fix YAML Configuration: Correct any YAML syntax errors. For example, a minimal

.bandit

configuration may look like:

---
exclude_dirs:
  - /tests/
  - /test/
  - .venv/
  - venv/

Create ESLint Configuration (if missing): If ESLint reports a missing configuration, create an

.eslintrc.json

file:

{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "extends": "eslint:recommended",
  "parserOptions": {
    "ecmaVersion": 12,
    "sourceType": "module"
  },
  "rules": {}
}

Auto-Fix Formatting Issues: Stage all changes (
```
git add -u
```
) and recommit to allow pre-commit to auto-fix formatting issues (YAML, Markdown, etc.).
Run All pre-commit checks: Use
```
pre-commit run --all-files || true
```
to attempt auto-fixing all issues.
Add auto-fixes: Use
```
git add -A
```
to stage the auto-fixed changes.

Commit: Use

git commit -m "chore: fix pre-commit issues and format code"

to commit the staged changes.

Bypass (If Necessary): If pre-commit hooks persist, temporarily bypass them using
```
git commit --no-verify -m "chore: commit all changes (pre-commit fixes to follow)"
```
. Use this as a last resort.

Pre-commit Hook Dependency Conflict:

When pre-commit hooks fail due to dependency conflicts, especially with
```
mdformat
```
, update to a compatible version that works with GFM plugins.
Specifically, ensure that the
```
mdformat
```
hook in
```
.pre-commit-config-rapid.yaml
```
is using a compatible revision and includes the necessary
```
additional_dependencies
```
.

Example:

# ...existing code...
- repo: https://github.com/executablebooks/mdformat
  rev: 0.7.17 # Compatible with gfm plugins
  hooks:
    - id: mdformat
      additional_dependencies:
        - mdformat-gfm>=0.3.5
        - mdformat-tables
        - mdformat-toc
  args: [--wrap, '120']
# ...existing code...

Resolution Steps:

Examine Current Configuration: Check the current
```
mdformat
```
configuration in
```
.pre-commit-config-rapid.yaml
```
.

Apply the Fix: Update the

mdformat

configuration to use

rev: 0.7.17

and include

mdformat-gfm>=0.3.5

mdformat-tables

, and

mdformat-toc

additional_dependencies

. Ensure

args: [--wrap, '120']

is also present.

Check for Rapid Config: If
```
.pre-commit-config-rapid.yaml
```
exists, apply the same fix to it.

Clean and Reinstall: Run

pre-commit clean

pre-commit install

, and

pre-commit autoupdate --repo https://github.com/executablebooks/mdformat

Test the Fix: Run

pre-commit run mdformat --all-files

and

pre-commit run --all-files

to verify the fix.

Update Documentation: Remove any

--no-verify

workarounds from

docs/

CONTRIBUTING.md

README.md

, and

CLEANUP_ROADMAP.md

Commit the Fix: Stage the changes and commit with the message:

fix: update mdformat to v0.7.17 for gfm plugin compatibility - Update mdformat from 1.0.0 to 0.7.17 - Maintains compatibility with mdformat-gfm>=0.3.5 - Fixes pre-commit hook dependency conflict - Resolves CLEANUP_ROADMAP Phase 1.1 - Closes #[issue-number] The previous version (1.0.0) was incompatible with mdformat-gfm plugins, forcing developers to use --no-verify and bypass quality gates. Testing: - ✅ pre-commit run --all-files passes - ✅ mdformat hook executes successfully - ✅ All markdown files formatted correctly

Directory Case Sensitivity Issues:
- To prevent future merge conflicts, standardize directory casing.
- Consolidate directories to lowercase. Example: Consolidate
```
Jules
```
  to
```
jules
```
  .
- Update all workflow references to use the lowercase directory name.
- Add the uppercase directory name to
```
.gitignore
```
  .

FINAL DOs AND DON'Ts

GitHub Copilot Enhancement Resources

New to GitHub Copilot customizations? This organization provides comprehensive enhancements:

📘 Quick Start Guide - Get up and running in 15 minutes
🔧 Custom Instructions Setup - Configure coding standards (100+ available)
🔌 MCP Server Setup - Extend Copilot with Model Context Protocol (11 languages)
💻 Development Environment Setup - Optimize your dev environment
📚 Complete Index - Browse all resources

The following instructions are only to be applied when performing a code review.

README updates

The new file should be added to the
```
README.md
```
.

Prompt file guide

Only apply to files that end in

.prompt.md

The prompt has markdown front matter.
The prompt has a
```
mode
```
field specified of either
```
agent
```
or
```
ask
```
.
The prompt has a
```
description
```
field.
The
```
description
```
field is not empty.
The
```
description
```
field value is wrapped in single quotes.
The file name is lower case, with words separated by hyphens.
Encourage the use of
```
tools
```
, but it's not required.
Strongly encourage the use of
```
model
```
to specify the model that the prompt is optimised for.

Instruction file guide

Only apply to files that end in

.instructions.md

The instruction has markdown front matter.
The instruction has a
```
description
```
field.
The
```
description
```
field is not empty.
The
```
description
```
field value is wrapped in single quotes.
The file name is lower case, with words separated by hyphens.
The instruction has an
```
applyTo
```
field that specifies the file or files to which the instructions apply. If they wish to specify multiple file paths they should be formated like
```
'**.js, **.ts'
```
.

Chat Mode file guide

Only apply to files that end in

.chatmode.md

The chat mode has markdown front matter.
The chat mode has a
```
description
```
field.
The
```
description
```
field is not empty.
The
```
description
```
field value is wrapped in single quotes.
The file name is lower case, with words separated by hyphens.
Encourage the use of
```
tools
```
, but it's not required.
Strongly encourage the use of
```
model
```
to specify the model that the chat mode is optimised for.

Code Review Workflow Rules

When performing a code review, pay close attention to the following:

Security:
- High - If an iframe embed runs with
```
sandbox="allow-scripts allow-same-origin ..."
```
  , flag it. Allowing both script execution and same-origin breaks the sandbox boundary, so a compromised demo can read or inject content into the parent gallery. The sandbox should be tightened or the content proxied.

Deployment Registry and Data Aggregation:
- High - Ensure that deployment workflows are not overwriting a central YAML file (
```
app-deployments.yml
```
  ) inside the source repo, especially if the gallery is in a separate
```
.github
```
  repo and the index job only queries GitHub APIs. Commits to the source repo will not reach the gallery site, and the deployment registry will remain empty, preventing live demos from being surfaced in the UI.

Stash Management Rules

When encountering a large number of stashed changes and ongoing issues:

Triage Plan:
- When there are a large number of stashed changes, start with a triage plan.
- Gather concise
```
git status
```
  .
- Summarize stashes.
- Prioritize which stashes to address.
Triage Options:
- Collect
```
git status
```
  and a stash inventory summary (count + newest/oldest entries).
- Focus on active issues that need fixing - ask the user to specify the issues or failing workflow.
- Prune stale stashes after backing up important ones.
Execution:
- When handling a large number of stashed changes and ongoing issues with autonomous approval:
  - Run
```
git status -sb
```
    to get the current working tree status.
  - Summarize stashes using:
```
(git stash list | head -n 5; echo '---'; git stash list | tail -n 5; echo '---count---'; git stash list | wc -l)
```
    .

Phase 2: Documentation Consolidation (Priority: 🟡 HIGH)

2.1 Consolidate Duplicate Documentation

Compare content of three ROADMAP files
Keep docs/ROADMAP.md as canonical
Move workflow-specific content
Add redirect/deprecation notices
Update internal links
Create docs/INDEX.md

2.2 Restructure Documentation Hierarchy

Create docs/INDEX.md master index
Reorganize files into subdirectories (guides/, reference/, workflows/, audits/, architecture/)
Update cross-references
Add navigation breadcrumbs

2.3 Update Root-Level Documentation

Add badges to README.md
Create visual architecture diagram
Add quickstart section
Update contact emails
Add "Last Updated" footer
Create CHANGELOG.md

Phase 3: Code & Script Cleanup (Priority: 🟡 HIGH)

Timeline: 5-7 days
Owner: Engineering Team

The phase includes:

3.1 Consolidate Agent Tracking Systems - Document purpose of agent trackers, consolidate to single .jules/ directory, create docs, add validation tests
3.2 Audit and Optimize Python Scripts - Add docstrings, run mypy --strict, achieve 80%+ test coverage, remove deprecated scripts, create README
3.3 Shell Script Cleanup - Run shellcheck, add error handling, add usage/help messages, document env vars
3.4 Remove Build Artifacts - Ensure .gitignore covers temp files, create cleanup script, add pre-commit hook

Phase 4: Workflow Optimization (Priority: 🟢 MEDIUM)

Timeline: 1-2 weeks
Owner: DevOps Team

Key tasks:

4.1 Audit All Workflows - Generate workflow inventory
4.2 Fix Workflow Health Issues - Issues #193, #207 (21 errors, 20 warnings)
4.3 Consolidate Reusable Workflows - Reduce duplication
4.4 Optimize Workflow Triggers - Reduce unnecessary runs
4.5 Documentation & Migration - Create reusable workflows guide, migrate workflows

Phase 5: Security & Compliance (Priority: 🔴 HIGH)

Timeline: 1 week
Owner: Security Committee

5.1 Security Fixes - Eliminate public security disclosure, enhance PII protection
5.2 Secret Scanning - Verify no secrets, create comprehensive security guide
5.3 Dependency Security - Audit all dependencies, create dependency management guide

GitHub Copilot Enhancement Resources

New to GitHub Copilot customizations? This organization provides comprehensive enhancements:

📘 Quick Start Guide - Get up and running in 15 minutes
🔧 Custom Instructions Setup - Configure coding standards (100+ available)
🔌 MCP Server Setup - Extend Copilot with Model Context Protocol (11 languages)
💻 Development Environment Setup - Optimize your dev environment
📚 Complete Index - Browse all resources

The following instructions are only to be applied when performing a code review.

README updates

The new file should be added to the
```
README.md
```
.

Prompt file guide

Only apply to files that end in

.prompt.md

The prompt has markdown front matter.
The prompt has a
```
mode
```
field specified of either
```
agent
```
or
```
ask
```
.
The prompt has a
```
description
```
field.
The
```
description
```
field is not empty.
The
```
description
```
field value is wrapped in single quotes.
The file name is lower case, with words separated by hyphens.
Encourage the use of
```
tools
```
, but it's not required.
Strongly encourage the use of
```
model
```
to specify the model that the prompt is optimised for.

Instruction file guide

Only apply to files that end in

.instructions.md

The instruction has markdown front matter.
The instruction has a
```
description
```
field.
The
```
description
```
field is not empty.
The
```
description
```
field value is wrapped in single quotes.