diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 4bf3e43..423b0f7 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,3 +1,9 @@ +{"id":"ai-development-patterns-4l4","title":"Promote Event Automation from experiments to main patterns","description":"## Goal\nPromote the **Event Automation** experimental pattern to a stable, top-level pattern.\n\n## References\n- `pattern-spec.md` (required template + naming/anchor rules)\n- `PATTERN_MIGRATION_GUIDE.md` (canonical naming + anchor conventions)\n\n\u003e Note: `PATTERN_RENAME_IMPLEMENTATION_PLAN.md` was not found in the repo root; follow the naming rules above.\n\n## Pattern Content Promotion\n- Move example implementation: `experiments/examples/event-automation/` → `examples/event-automation/`.\n- Review and update internal links inside the moved example docs so they resolve to the new canonical section in root `README.md`.\n- Promote the pattern narrative currently in `experiments/README.md` (`### Event Automation`) into main `README.md` under `# Development Patterns`.\n- Ensure the promoted pattern section conforms to the `pattern-spec.md` structure:\n - **Maturity**, **Description**, **Related Patterns** (hyperlinked)\n - Implementation content + at least one **Anti-pattern**\n - **Complete Implementation** link to `examples/event-automation/`\n- Assign maturity/type (expected: **Intermediate**, **Development**).\n\n## Root README.md Updates (`README.md`)\n- Add a new row to **Complete Pattern Reference** table:\n - Pattern: `Event Automation`\n - Maturity/Type/Description/Dependencies\n - Ensure dependencies are stable patterns only (likely `Codified Rules`, `Security Sandbox`).\n- Add the full **Event Automation** section under `# Development Patterns`.\n- Update **Pattern Dependencies \u0026 Implementation Order** (`graph TD` block) to include Event Automation where appropriate.\n- Update contextual guidance sections if applicable:\n - `### Context-Based Pattern Selection` (Development Teams / Enterprise)\n - `### Project Type Recommendations`\n - `### Team Size Considerations`\n- Update pattern count badges after updating tests via `python3 scripts/update-pattern-count.py` (updates `README.md` and `index.html`).\n\n## Cross-Reference Updates\n- Remove Event Automation from:\n - `experiments/README.md` reference table and its full pattern section.\n - `experiments/examples/README.md` example catalog table.\n- Update references in docs:\n - `docs/ai-development-best-practices.md`: update the Event Automation link from `../experiments/README.md#event-automation` → `../README.md#event-automation` (or the appropriate relative path).\n- Update **Related Patterns** in other main patterns that should reference Event Automation (edit relevant sections in `README.md`):\n - [Codified Rules](README.md#codified-rules)\n - [Security Sandbox](README.md#security-sandbox)\n - [Custom Commands](README.md#custom-commands) once promoted\n - [Progressive Disclosure](README.md#progressive-disclosure) once promoted\n- Repo-wide search to update any remaining links:\n - Search for `Event Automation`, `#event-automation`, and `experiments/README.md#event-automation`.\n\n## Supporting File Updates\n- Tests / validation lists:\n - `tests/conftest.py`: add **Event Automation** to `EXPECTED_PATTERNS` and `PATTERN_CATEGORIES` (Development).\n- Ensure CI stays green:\n - `.github/workflows/pattern-validation.yml` (no change expected, but confirm)\n - Run local suite (at minimum): `pytest -q`\n- Check for references in config:\n - `CLAUDE.md`\n - `.ai/` rules/prompts\n\n## Acceptance Criteria\n- Event Automation is documented in `README.md` (table + full pattern section) and removed from `experiments/README.md`.\n- Example implementation is moved to `examples/event-automation/` and removed from `experiments/examples/`.\n- `docs/ai-development-best-practices.md` links to `README.md#event-automation` (not experimental anchors).\n- No remaining links reference `experiments/README.md#event-automation`; full `pattern-validation.yml` test suite passes.\n","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-02-05T09:50:46.967314-05:00","created_by":"Paul Duvall","updated_at":"2026-02-05T11:28:33.496429-05:00","closed_at":"2026-02-05T11:28:33.496429-05:00","close_reason":"Closed","labels":["pattern-promotion"]} +{"id":"ai-development-patterns-aqy","title":"Promote Custom Commands from experiments to main patterns","description":"## Goal\nPromote the **Custom Commands** experimental pattern to a stable, top-level pattern.\n\n## References\n- `pattern-spec.md` (required template + naming/anchor rules)\n- `PATTERN_MIGRATION_GUIDE.md` (canonical naming + anchor conventions)\n\n\u003e Note: `PATTERN_RENAME_IMPLEMENTATION_PLAN.md` was not found in the repo root; follow the naming rules above.\n\n## Pattern Content Promotion\n- Move example implementation: `experiments/examples/custom-commands/` → `examples/custom-commands/`.\n- Review and update internal links inside the moved example docs so they resolve to the new canonical section in root `README.md`.\n- Promote the pattern narrative currently in `experiments/README.md` (`### Custom Commands`) into main `README.md` under `# Development Patterns`.\n- Ensure the promoted pattern section conforms to the `pattern-spec.md` structure:\n - **Maturity**, **Description**, **Related Patterns** (hyperlinked)\n - Implementation content + at least one **Anti-pattern**\n - **Complete Implementation** link to `examples/custom-commands/`\n- Assign maturity/type (expected: **Intermediate**, **Development**).\n\n## Root README.md Updates (`README.md`)\n- Add a new row to **Complete Pattern Reference** table:\n - Pattern: `Custom Commands`\n - Maturity/Type/Description/Dependencies\n - Ensure dependencies are stable patterns only (expected: `Event Automation`, `Spec-Driven Development`, `Codified Rules`).\n- Add the full **Custom Commands** section under `# Development Patterns`.\n- Update **Pattern Dependencies \u0026 Implementation Order** (`graph TD` block) if Custom Commands changes recommended sequencing.\n- Update contextual guidance sections if applicable:\n - `### Context-Based Pattern Selection` (Development Teams)\n - `### Project Type Recommendations`\n - `### Team Size Considerations`\n- Update pattern count badges after updating tests via `python3 scripts/update-pattern-count.py` (updates `README.md` and `index.html`).\n\n## Cross-Reference Updates\n- Remove Custom Commands from:\n - `experiments/README.md` reference table and its full pattern section.\n - `experiments/examples/README.md` example catalog table.\n- Update references in docs:\n - `docs/ai-development-best-practices.md`: update the Custom Commands link from `../experiments/README.md#custom-commands` → `../README.md#custom-commands` (or the appropriate relative path).\n - `docs/claude-code-guide.md`: consider adding a canonical link to the pattern section (if helpful), but avoid changing content unnecessarily.\n- Update **Related Patterns** in other main patterns that should reference Custom Commands (edit relevant sections in `README.md`):\n - [Spec-Driven Development](README.md#spec-driven-development)\n - [Event Automation](README.md#event-automation) once promoted\n - [Codified Rules](README.md#codified-rules)\n - [Progressive Disclosure](README.md#progressive-disclosure) once promoted\n- Repo-wide search to update any remaining links:\n - Search for `Custom Commands`, `#custom-commands`, and `experiments/README.md#custom-commands`.\n\n## Supporting File Updates\n- Tests / validation lists:\n - `tests/conftest.py`: add **Custom Commands** to `EXPECTED_PATTERNS` and `PATTERN_CATEGORIES` (Development).\n- Ensure CI stays green:\n - `.github/workflows/pattern-validation.yml` (no change expected, but confirm)\n - Run local suite (at minimum): `pytest -q`\n- Check for references in config:\n - `CLAUDE.md`\n - `.ai/` rules/prompts\n\n## Acceptance Criteria\n- Custom Commands is documented in `README.md` (table + full pattern section) and removed from `experiments/README.md`.\n- Example implementation is moved to `examples/custom-commands/` and removed from `experiments/examples/`.\n- `docs/ai-development-best-practices.md` links to `README.md#custom-commands` (not experimental anchors).\n- No remaining links reference `experiments/README.md#custom-commands`; full `pattern-validation.yml` test suite passes.\n","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-02-05T09:51:10.109694-05:00","created_by":"Paul Duvall","updated_at":"2026-02-05T11:35:43.536445-05:00","closed_at":"2026-02-05T11:35:43.536445-05:00","close_reason":"Closed","labels":["pattern-promotion"],"dependencies":[{"issue_id":"ai-development-patterns-aqy","depends_on_id":"ai-development-patterns-4l4","type":"blocks","created_at":"2026-02-05T09:52:09.393058-05:00","created_by":"Paul Duvall"}]} +{"id":"ai-development-patterns-arv","title":"Promote Image Spec from experiments to main patterns","description":"## Goal\nPromote the **Image Spec** experimental pattern to a stable, top-level pattern.\n\n## References\n- `pattern-spec.md` (required template + naming/anchor rules)\n- `PATTERN_MIGRATION_GUIDE.md` (canonical naming + anchor conventions)\n\n\u003e Note: `PATTERN_RENAME_IMPLEMENTATION_PLAN.md` was not found in the repo root; follow the naming rules above.\n\n## Pattern Content Promotion\n- Promote the pattern narrative currently in `experiments/README.md` (`### Image Spec`) into main `README.md` under `# Development Patterns`.\n- Create a new complete implementation directory (since no experimental example dir exists today):\n - Add `examples/image-spec/README.md` with concrete, repeatable workflows (attach diagram → prompt template → iteration loop).\n - Include lightweight sample assets (e.g., simple SVG/PNG diagrams) if appropriate, or document how to generate them.\n- Ensure the promoted pattern section conforms to the `pattern-spec.md` structure:\n - **Maturity**, **Description**, **Related Patterns** (hyperlinked)\n - Implementation content + at least one **Anti-pattern**\n - **Complete Implementation** link to `examples/image-spec/`\n- Assign maturity/type (expected: **Intermediate**, **Development**).\n- Reconcile dependencies so the **main** reference table does not depend on experimental-only patterns (e.g., `Context Optimization`). If needed, keep experimental patterns as non-dependency “Related Patterns” links instead.\n\n## Root README.md Updates (`README.md`)\n- Add a new row to **Complete Pattern Reference** table:\n - Pattern: `Image Spec`\n - Maturity/Type/Description/Dependencies (dependencies must be patterns in main `README.md`)\n- Add the full **Image Spec** section under `# Development Patterns`.\n- Update **Pattern Dependencies \u0026 Implementation Order** (`graph TD` block) if Image Spec changes recommended sequencing.\n- Update contextual guidance sections if applicable:\n - `### Context-Based Pattern Selection` (Development Teams)\n - `### Project Type Recommendations` (MVP/Startup, UI-heavy)\n - `### Team Size Considerations`\n- Update pattern count badges after updating tests via `python3 scripts/update-pattern-count.py` (updates `README.md` and `index.html`).\n\n## Cross-Reference Updates\n- Remove Image Spec from `experiments/README.md` reference table and remove its full pattern section.\n- Update references in docs:\n - `docs/ai-development-best-practices.md`: update the Image Spec link from `../experiments/README.md#image-spec` → `../README.md#image-spec` (or the appropriate relative path).\n- Update **Related Patterns** in other main patterns that should reference Image Spec (edit relevant sections in `README.md`):\n - [Spec-Driven Development](README.md#spec-driven-development)\n - [Progressive Enhancement](README.md#progressive-enhancement)\n- Repo-wide search to update any remaining links:\n - Search for `Image Spec`, `#image-spec`, and `experiments/README.md#image-spec`.\n\n## Supporting File Updates\n- Tests / validation lists:\n - `tests/conftest.py`: add **Image Spec** to `EXPECTED_PATTERNS` and `PATTERN_CATEGORIES` (Development).\n- Ensure CI stays green:\n - `.github/workflows/pattern-validation.yml` (no change expected, but confirm)\n - Run local suite (at minimum): `pytest -q`\n- Check for references in config:\n - `CLAUDE.md`\n - `.ai/` rules/prompts\n\n## Acceptance Criteria\n- Image Spec is documented in `README.md` (table + full pattern section) and removed from `experiments/README.md`.\n- `examples/image-spec/` exists with a usable, repo-appropriate “complete implementation” (docs + sample assets) and is linked from the pattern section.\n- `docs/ai-development-best-practices.md` links to `README.md#image-spec` (not experimental anchors).\n- Main reference-table dependencies do not require experimental-only patterns; full `pattern-validation.yml` test suite passes.\n","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-02-05T09:51:31.651548-05:00","created_by":"Paul Duvall","updated_at":"2026-02-05T11:50:17.115009-05:00","closed_at":"2026-02-05T11:50:17.115009-05:00","close_reason":"Closed","labels":["pattern-promotion"]} +{"id":"ai-development-patterns-b0z","title":"Verify migration of 5 experimental patterns to main","description":"## Goal\nRun end-to-end verification after promoting these 5 patterns from `experiments/` into the main catalog:\n- Centralized Rules\n- Progressive Disclosure\n- Event Automation\n- Custom Commands\n- Image Spec\n\n## Validation Checklist\n### Links \u0026 Anchors\n- Run internal link validation:\n - `pytest tests/test_links.py -q`\n - `pytest tests/test_readme_accuracy.py -q`\n- Repo-wide grep for stale experimental links:\n - `rg \"experiments/README.md#(centralized-rules|progressive-disclosure|event-automation|custom-commands|image-spec)\" -S .`\n\n### Mermaid Diagrams\n- Confirm Mermaid syntax tests pass:\n - `pytest tests/test_diagram.py -q`\n- Manually spot-check rendering on GitHub for:\n - `README.md` top overview graph\n - `README.md` “Pattern Dependencies \u0026 Implementation Order” diagram\n - Any new diagrams added during promotion\n\n### Pattern Count + Reference Table\n- Verify pattern count badge is correct and in sync:\n - `python3 scripts/update-pattern-count.py`\n - Ensure `git diff --exit-code README.md index.html`\n- Verify `README.md` Complete Pattern Reference table matches implemented sections:\n - `pytest tests/test_pattern_compliance.py -q`\n - `pytest tests/test_readme_accuracy.py -q`\n\n### Example Directories\n- Validate examples are healthy after moving/adding directories:\n - `pytest tests/test_examples.py -q`\n- Confirm example directories moved from `experiments/examples/` to `examples/` and all links still resolve.\n\n### Dependencies\n- Validate no missing or circular dependencies:\n - `pytest tests/test_dependencies.py -q`\n- Confirm dependencies for promoted patterns reference only main patterns (no experimental-only dependencies in the main reference table).\n\n### Experiments Catalog Hygiene\n- Confirm `experiments/README.md`:\n - No longer lists the 5 promoted patterns in the experimental reference table.\n - No longer contains the full pattern sections for the 5 patterns.\n- Confirm `experiments/examples/README.md`:\n - No longer lists example directories for Centralized Rules / Event Automation / Custom Commands.\n\n### CI Workflow Parity\n- Ensure local results match what `.github/workflows/pattern-validation.yml` runs (pattern compliance, readme accuracy, link validation, example validation, dependencies, diagram validation).\n\n## Acceptance Criteria\n- All internal links and anchors resolve (no broken links/anchors in `README.md`, `docs/`, `examples/`).\n- Mermaid diagrams render without syntax errors; `pytest tests/test_diagram.py` passes.\n- Pattern count badge matches the updated `tests/conftest.py` count; `python3 scripts/update-pattern-count.py` produces no diff.\n- Full local test suite passes (equivalent to `.github/workflows/pattern-validation.yml`).\n- `experiments/README.md` and `experiments/examples/README.md` no longer list: Centralized Rules, Progressive Disclosure, Event Automation, Custom Commands, Image Spec.\n","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-02-05T09:51:53.777977-05:00","created_by":"Paul Duvall","updated_at":"2026-02-05T11:56:35.63418-05:00","closed_at":"2026-02-05T11:56:35.63418-05:00","close_reason":"Closed","labels":["pattern-promotion"],"dependencies":[{"issue_id":"ai-development-patterns-b0z","depends_on_id":"ai-development-patterns-x36","type":"blocks","created_at":"2026-02-05T09:52:09.718533-05:00","created_by":"Paul Duvall"},{"issue_id":"ai-development-patterns-b0z","depends_on_id":"ai-development-patterns-dxt","type":"blocks","created_at":"2026-02-05T09:52:09.803985-05:00","created_by":"Paul Duvall"},{"issue_id":"ai-development-patterns-b0z","depends_on_id":"ai-development-patterns-4l4","type":"blocks","created_at":"2026-02-05T09:52:09.882079-05:00","created_by":"Paul Duvall"},{"issue_id":"ai-development-patterns-b0z","depends_on_id":"ai-development-patterns-aqy","type":"blocks","created_at":"2026-02-05T09:52:09.960215-05:00","created_by":"Paul Duvall"},{"issue_id":"ai-development-patterns-b0z","depends_on_id":"ai-development-patterns-arv","type":"blocks","created_at":"2026-02-05T09:52:10.042535-05:00","created_by":"Paul Duvall"}]} +{"id":"ai-development-patterns-dxt","title":"Promote Progressive Disclosure from experiments to main patterns","description":"## Goal\nPromote the **Progressive Disclosure** experimental pattern to a stable, top-level pattern.\n\n## References\n- `pattern-spec.md` (required template + naming/anchor rules)\n- `PATTERN_MIGRATION_GUIDE.md` (canonical naming + anchor conventions)\n\n\u003e Note: `PATTERN_RENAME_IMPLEMENTATION_PLAN.md` was not found in the repo root; follow the naming rules above.\n\n## Pattern Content Promotion\n- Promote the pattern narrative currently in `experiments/README.md` (`### Progressive Disclosure`) into main `README.md` under `# Development Patterns`.\n- Ensure the promoted pattern section conforms to the `pattern-spec.md` structure:\n - **Maturity**, **Description**, **Related Patterns** (hyperlinked)\n - Implementation content + at least one **Anti-pattern**\n - Add/ensure a **Complete Implementation** link (create `examples/progressive-disclosure/` if needed)\n- Assign maturity/type (expected: **Intermediate**, **Development**).\n- Reconcile dependencies so the **main** reference table does not depend on experimental-only patterns (e.g., `Context Optimization`). If needed, keep experimental patterns as non-dependency “Related Patterns” links instead.\n\n## Root README.md Updates (`README.md`)\n- Add a new row to **Complete Pattern Reference** table:\n - Pattern: `Progressive Disclosure`\n - Maturity/Type/Description/Dependencies (dependencies must be patterns in main `README.md`)\n - Place in the Development section near `Codified Rules` / `Context Persistence` / `Custom Commands`.\n- Add the full **Progressive Disclosure** section under `# Development Patterns`.\n- Update **Pattern Dependencies \u0026 Implementation Order** (`graph TD` block) if Progressive Disclosure changes recommended sequencing.\n- Update contextual guidance sections if applicable:\n - `### Context-Based Pattern Selection` (Development Teams)\n - `### Project Type Recommendations`\n - `### Team Size Considerations`\n- Update pattern count badges after updating tests via `python3 scripts/update-pattern-count.py` (updates `README.md` and `index.html`).\n\n## Cross-Reference Updates\n- Remove Progressive Disclosure from `experiments/README.md` reference table and remove its full pattern section.\n- Update repo-wide references:\n - `README.md`: convert the existing **Progressive Disclosure** mention in the `Context Persistence` principles list into a hyperlink to `#progressive-disclosure`.\n - `experiments/examples/centralized-rules/sync-strategy/example-central-repo/base/universal-rules.md`: evaluate whether to add a link/anchor reference to the promoted pattern.\n- Update **Related Patterns** in other main patterns that should reference Progressive Disclosure (edit the relevant sections in `README.md`):\n - [Codified Rules](README.md#codified-rules)\n - [Context Persistence](README.md#context-persistence)\n - [Event Automation](README.md#event-automation) once promoted\n - [Custom Commands](README.md#custom-commands) once promoted\n - [Centralized Rules](README.md#centralized-rules) once promoted\n- Repo-wide search to update any remaining links:\n - Search for `Progressive Disclosure`, `#progressive-disclosure`, and `experiments/README.md#progressive-disclosure`.\n\n## Supporting File Updates\n- Tests / validation lists:\n - `tests/conftest.py`: add **Progressive Disclosure** to `EXPECTED_PATTERNS` and `PATTERN_CATEGORIES` (Development).\n- Docs/config references (update if present):\n - `CLAUDE.md`\n - `.ai/` rules/prompts\n- Verify workflows/tests:\n - `.github/workflows/pattern-validation.yml`\n - Run local suite (at minimum): `pytest -q`\n\n## Acceptance Criteria\n- Progressive Disclosure is documented in `README.md` (table + full pattern section) and removed from `experiments/README.md`.\n- A complete implementation link exists (and `examples/progressive-disclosure/` exists, if added as part of promotion).\n- Root README cross-references (e.g., `Context Persistence` principle list) link to `#progressive-disclosure`.\n- No remaining links reference `experiments/README.md#progressive-disclosure`; full `pattern-validation.yml` test suite passes.\n","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-02-05T09:50:24.249155-05:00","created_by":"Paul Duvall","updated_at":"2026-02-05T11:40:54.574087-05:00","closed_at":"2026-02-05T11:40:54.574087-05:00","close_reason":"Closed","labels":["pattern-promotion"],"dependencies":[{"issue_id":"ai-development-patterns-dxt","depends_on_id":"ai-development-patterns-4l4","type":"blocks","created_at":"2026-02-05T09:52:09.472232-05:00","created_by":"Paul Duvall"},{"issue_id":"ai-development-patterns-dxt","depends_on_id":"ai-development-patterns-aqy","type":"blocks","created_at":"2026-02-05T09:52:09.554501-05:00","created_by":"Paul Duvall"}]} +{"id":"ai-development-patterns-x36","title":"Promote Centralized Rules from experiments to main patterns","description":"## Goal\nPromote the **Centralized Rules** experimental pattern to a stable, top-level pattern.\n\n## References\n- `pattern-spec.md` (required template + naming/anchor rules)\n- `PATTERN_MIGRATION_GUIDE.md` (canonical naming + anchor conventions)\n\n\u003e Note: `PATTERN_RENAME_IMPLEMENTATION_PLAN.md` was not found in the repo root; follow the naming rules above.\n\n## Pattern Content Promotion\n- Move example implementation: `experiments/examples/centralized-rules/` → `examples/centralized-rules/`.\n- Review and update internal links inside the moved example docs (e.g., any `../../README.md#...` references) so they resolve to the new canonical section in root `README.md`.\n- Ensure the promoted pattern section conforms to the `pattern-spec.md` structure:\n - **Maturity**, **Description**, **Related Patterns** (hyperlinked)\n - Implementation content + at least one **Anti-pattern**\n - **Complete Implementation** link(s) to `examples/centralized-rules/` subdirectories\n- Confirm maturity/type are set appropriately (expected: **Advanced**, **Operations**).\n\n## Root README.md Updates (`README.md`)\n- Add a new row to **Complete Pattern Reference** table:\n - Pattern: `Centralized Rules`\n - Maturity/Type/Description/Dependencies (ensure dependencies point only to patterns in main `README.md`)\n - Place under the appropriate Operations sub-category row (likely **Security \u0026 Compliance**).\n- Add a full **Centralized Rules** pattern section under `# Operations Patterns` (likely within `## Security \u0026 Compliance Patterns`) by promoting/adapting content from `experiments/README.md`.\n- Update **Pattern Dependencies \u0026 Implementation Order** (`graph TD` block) to include Centralized Rules and its prerequisites.\n- Update contextual guidance sections if applicable:\n - `### Context-Based Pattern Selection` (Enterprise/Production)\n - `### Project Type Recommendations` (Enterprise)\n - `### Team Size Considerations` (Multi-team orgs)\n- Update pattern count badges after updating tests via `python3 scripts/update-pattern-count.py` (updates `README.md` and `index.html`).\n\n## Cross-Reference Updates\n- Remove Centralized Rules from:\n - `experiments/README.md` reference table and its full pattern section.\n - `experiments/examples/README.md` example catalog table.\n- Update **Related Patterns** in other main patterns that should reference Centralized Rules (edit the relevant sections in `README.md`):\n - [Codified Rules](README.md#codified-rules)\n - [Policy Generation](README.md#policy-generation)\n - [Security Orchestration](README.md#security-orchestration)\n - [Security Sandbox](README.md#security-sandbox) (if relevant)\n - [Progressive Disclosure](README.md#progressive-disclosure) once promoted\n- Repo-wide search to update any remaining links:\n - Search for `Centralized Rules`, `#centralized-rules`, and `experiments/README.md#centralized-rules`.\n\n## Supporting File Updates\n- Tests / validation lists:\n - `tests/conftest.py`: add **Centralized Rules** to `EXPECTED_PATTERNS` and `PATTERN_CATEGORIES` (Operations).\n- Verify workflows/tests still pass with new paths:\n - `.github/workflows/pattern-validation.yml` (no change expected, but confirm)\n - Run local suite (at minimum): `pytest -q`\n- Check for references in config/docs:\n - `CLAUDE.md` (update if it references the pattern)\n - `.ai/` rule/prompt files (update if they reference experimental paths)\n\n## Acceptance Criteria\n- Centralized Rules is documented in `README.md` (table + full pattern section) and removed from `experiments/README.md`.\n- Example implementation lives at `examples/centralized-rules/` and no longer under `experiments/examples/`.\n- All repo references point to `README.md#centralized-rules` (no remaining `experiments/README.md#centralized-rules` links).\n- `python3 scripts/update-pattern-count.py` produces no diff after changes; full `pattern-validation.yml` test suite passes.\n","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-02-05T09:50:01.543467-05:00","created_by":"Paul Duvall","updated_at":"2026-02-05T11:46:11.430469-05:00","closed_at":"2026-02-05T11:46:11.430469-05:00","close_reason":"Closed","labels":["pattern-promotion"],"dependencies":[{"issue_id":"ai-development-patterns-x36","depends_on_id":"ai-development-patterns-dxt","type":"blocks","created_at":"2026-02-05T09:52:09.638866-05:00","created_by":"Paul Duvall"}]} {"id":"ai-development-patterns-zqc","title":"Epic: Repo consistency + link health alignment","description":"Audit findings (2026-01-31):\n\n- README passes pattern-spec + hyperlink tests (including slow external link check).\n- 65 broken internal/relative links across 20 non-README markdown files (mostly stale anchors/paths from pre-migration naming).\n- Stable example directories are named correctly, but almost all example READMEs still use pre-migration pattern names (e.g., 'Rules as Code', 'AI Security Sandbox', etc.) and contain stale links.\n- Experimental docs/examples still reference old pattern names/anchors and some example READMEs reference missing files.\n- CLAUDE.md repo tree is out of date vs current directories.\n- index.html drifts from README (missing patterns + category mismatch).\n\nGoal: bring docs/examples/tests/scripts into alignment with pattern-spec.md conventions (names, links, structure) and ensure link integrity repo-wide.\n\nAcceptance:\n- All markdown internal/relative links validate repo-wide.\n- Examples/docs use current pattern names + anchors.\n- CI/tests cover links beyond README.","status":"closed","priority":2,"issue_type":"epic","owner":"pduvall@gmail.com","created_at":"2026-01-31T12:27:56.125938-05:00","created_by":"Paul Duvall","updated_at":"2026-01-31T14:00:23.012581-05:00","closed_at":"2026-01-31T14:00:23.012581-05:00","close_reason":"Closed"} {"id":"ai-development-patterns-zqc.1","title":"Fix placeholder links in pattern-spec.md","description":"pattern-spec.md currently contains markdown links that are meant to be examples/placeholders (e.g., [Pattern Name](#pattern-name-anchor), examples/pattern-name/). These render as broken links in link-audit tooling and undermine the spec’s own link-integrity guidance.\n\nScope:\n- pattern-spec.md: ensure example link syntax is presented as code/escaped text (not clickable broken links).\n\nNotes:\n- Link audit currently reports 4 broken internal/relative links in pattern-spec.md (missing internal anchor + missing file).","acceptance_criteria":"- pattern-spec.md contains no broken internal/relative links when running a repo-wide markdown link audit (excluding code blocks).\n- Example link formats remain clear (prefer code formatting/backticks or escaping).","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-01-31T12:28:41.576272-05:00","created_by":"Paul Duvall","updated_at":"2026-01-31T12:57:21.381704-05:00","closed_at":"2026-01-31T12:57:21.381704-05:00","close_reason":"Closed","dependencies":[{"issue_id":"ai-development-patterns-zqc.1","depends_on_id":"ai-development-patterns-zqc","type":"parent-child","created_at":"2026-01-31T12:28:41.576846-05:00","created_by":"Paul Duvall"}]} {"id":"ai-development-patterns-zqc.10","title":"Update experiments/examples/README.md to current experimental catalog","description":"experiments/examples/README.md appears to be from a pre-migration state and references:\n- Experimental pattern names that no longer exist (e.g., AI Workflow Orchestration, Comprehensive AI Testing Strategy).\n- Example directories that do not exist (e.g., human-ai-handoff/, comprehensive-ai-testing-strategy/).\n- Broken links to stable examples (e.g., ../../examples/specification-driven-development/).\n\nScope:\n- Rewrite the table to match the current experiments/README.md pattern list and the actual directory names under experiments/examples/.\n- Fix links to stable examples to use existing paths and current anchors.","acceptance_criteria":"- experiments/examples/README.md accurately reflects experiments/examples/* directory names.\n- All links in experiments/examples/README.md resolve (repo-wide markdown link audit shows 0 broken links).\n- Terminology matches the current experimental pattern names (no legacy AI-prefixed names unless explicitly called out as history).","status":"closed","priority":2,"issue_type":"task","owner":"pduvall@gmail.com","created_at":"2026-01-31T12:30:43.505984-05:00","created_by":"Paul Duvall","updated_at":"2026-01-31T13:36:01.715712-05:00","closed_at":"2026-01-31T13:36:01.715712-05:00","close_reason":"Closed","dependencies":[{"issue_id":"ai-development-patterns-zqc.10","depends_on_id":"ai-development-patterns-zqc","type":"parent-child","created_at":"2026-01-31T12:30:43.5065-05:00","created_by":"Paul Duvall"}]} diff --git a/README.md b/README.md index 5851207..11c041a 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Tests](https://github.com/PaulDuvall/ai-development-patterns/actions/workflows/pattern-validation.yml/badge.svg)](https://github.com/PaulDuvall/ai-development-patterns/actions/workflows/pattern-validation.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Documentation](https://img.shields.io/badge/docs-comprehensive-brightgreen.svg)](https://github.com/PaulDuvall/ai-development-patterns#ai-development-patterns) -[![Patterns](https://img.shields.io/badge/patterns-22-blue.svg)](#complete-pattern-reference) +[![Patterns](https://img.shields.io/badge/patterns-27-blue.svg)](#complete-pattern-reference) [![Quality Gate](https://img.shields.io/badge/quality%20gate-passing-brightgreen.svg)](https://github.com/PaulDuvall/ai-development-patterns/tree/main/tests) [![Hyperlinks](https://img.shields.io/badge/hyperlinks-validated-brightgreen.svg)](https://github.com/PaulDuvall/ai-development-patterns/actions/workflows/pattern-validation.yml) @@ -21,6 +21,7 @@ graph TB TI --> BM([Baseline
Management]) SS --> SO([Security
Orchestration]) SS --> PG([Policy
Generation]) + SO --> CZR([Centralized
Rules]) %% ROW 3: Development patterns (flows forward again) DL --> OD([Observable
Development]) @@ -29,10 +30,19 @@ graph TB CR --> GR([Guided
Refactoring]) CR --> CP([Context
Persistence]) RA --> IG([Issue
Generation]) + CR --> EA([Event
Automation]) + SS --> EA + EA --> CC([Custom
Commands]) + SD --> CC + CP --> PD([Progressive
Disclosure]) + CR --> PD + SD --> IS([Image
Spec]) + PD --> CZR %% ROW 4: Development chain PE([Progressive
Enhancement]) --> AD([Atomic
Decomposition]) AD --> PA([Parallel
Agents]) + PE --> IS %% STYLING classDef foundation fill:#a8d5ba,stroke:#2d5a3f,stroke-width:2px,color:#1a3a25 @@ -40,8 +50,8 @@ graph TB classDef operations fill:#f5b7b1,stroke:#c0392b,stroke-width:2px,color:#78281f class RA,CR,SS,DL,TI,IG,CP foundation - class PE,SD,AD,PA,OD,GR,AT development - class PG,SO,BM operations + class PE,SD,AD,PA,OD,GR,AT,EA,CC,PD,IS development + class PG,SO,BM,CZR operations %% CLICKABLE LINKS click RA "https://github.com/PaulDuvall/ai-development-patterns#readiness-assessment" @@ -58,8 +68,13 @@ graph TB click OD "https://github.com/PaulDuvall/ai-development-patterns#observable-development" click GR "https://github.com/PaulDuvall/ai-development-patterns#guided-refactoring" click AT "https://github.com/PaulDuvall/ai-development-patterns#automated-traceability" + click EA "https://github.com/PaulDuvall/ai-development-patterns#event-automation" + click CC "https://github.com/PaulDuvall/ai-development-patterns#custom-commands" + click PD "https://github.com/PaulDuvall/ai-development-patterns#progressive-disclosure" + click IS "https://github.com/PaulDuvall/ai-development-patterns#image-spec" click PG "https://github.com/PaulDuvall/ai-development-patterns#policy-generation" click SO "https://github.com/PaulDuvall/ai-development-patterns#security-orchestration" + click CZR "https://github.com/PaulDuvall/ai-development-patterns#centralized-rules" click BM "https://github.com/PaulDuvall/ai-development-patterns#baseline-management" ``` @@ -94,6 +109,10 @@ graph TD G --> I[Progressive Enhancement] H --> I I --> J[Choice Generation] + Q[Event Automation] + R[Custom Commands] + S[Progressive Disclosure] + U[Image Spec] G --> K[Atomic Decomposition] K --> L[Parallel Agents] end @@ -101,9 +120,21 @@ graph TD subgraph "Phase 3: Operations (Weeks 5-6)" C --> M[Policy Generation] M --> N[Security Orchestration] + N --> T[Centralized Rules] L --> O[Baseline Management] D --> P[Automated Traceability] end + + B --> Q + C --> Q + Q --> R + G --> R + B --> S + R --> S + B --> T + S --> T + G --> U + I --> U ``` **Continuous Implementation Note**: Security patterns ([Security Sandbox](#security-sandbox), AI Security & Compliance) and deployment patterns should be implemented continuously throughout development, not delayed until specific phases. The dependencies shown represent learning prerequisites, not deployment gates. @@ -119,6 +150,7 @@ graph TD | **[Tool Integration](#tool-integration)** | Intermediate | Foundation | Connect AI systems to external data sources, APIs, and tools for enhanced capabilities beyond prompt-only interactions | Security Sandbox, Developer Lifecycle | | **[Issue Generation](#issue-generation)** | Intermediate | Foundation | Generate Kanban-optimized work items (4-8 hours max) from requirements using AI to ensure continuous flow with clear acceptance criteria and dependencies | Readiness Assessment | | **[Spec-Driven Development](#spec-driven-development)** | Intermediate | Development | Use executable specifications to guide AI code generation with clear acceptance criteria before implementation | Developer Lifecycle | +| **[Image Spec](#image-spec)** | Intermediate | Development | Upload images (diagrams, mockups, flows) as primary specifications for AI coding tools to build accurate implementations from visual context | Spec-Driven Development, Progressive Enhancement | | **[Planned Implementation](#planned-implementation)** | Beginner | Development | Generate explicit implementation plans before writing code to improve quality, reduce iterations, and enable better collaboration | None | | **[Progressive Enhancement](#progressive-enhancement)** | Beginner | Development | Build complex features through small, deployable iterations rather than big-bang generation | None | | **[Choice Generation](#choice-generation)** | Intermediate | Development | Generate multiple implementation options for exploration and comparison rather than accepting first AI solution | Progressive Enhancement | @@ -126,6 +158,9 @@ graph TD | **[Parallel Agents](#parallel-agents)** | Advanced | Development | Run multiple AI agents concurrently on isolated tasks or environments to maximize development speed and exploration | Atomic Decomposition | | **[Context Persistence](#context-persistence)** | Intermediate | Development | Manage AI context as a finite resource through structured memory schemas, prompt pattern capture, and session continuity protocols | Codified Rules | | **[Constrained Generation](#constrained-generation)** | Beginner | Development | Give AI specific constraints to prevent over-engineering and ensure focused solutions | None | +| **[Event Automation](#event-automation)** | Intermediate | Development | Execute custom commands automatically at assistant lifecycle events to enforce policies and automate workflows | Codified Rules, Security Sandbox | +| **[Custom Commands](#custom-commands)** | Intermediate | Development | Discover and use built-in command vocabularies, then extend them with custom commands that encode domain expertise and sophisticated workflows | Event Automation, Spec-Driven Development, Codified Rules | +| **[Progressive Disclosure](#progressive-disclosure)** | Intermediate | Development | Load AI assistant rules incrementally based on task context to prevent instruction saturation and context bloat | Codified Rules, Context Persistence | | **[Observable Development](#observable-development)** | Intermediate | Development | Strategic logging and debugging that makes system behavior visible to AI | Developer Lifecycle | | **[Guided Refactoring](#guided-refactoring)** | Intermediate | Development | Systematic code improvement using AI to detect and resolve code smells with measurable quality metrics | Codified Rules | | **[Guided Architecture](#guided-architecture)** | Intermediate | Development | Apply architectural frameworks (DDD, Well-Architected, 12-Factor) using AI to ensure sound system design | Developer Lifecycle, Codified Rules | @@ -134,6 +169,7 @@ graph TD | **Security & Compliance** | | Operations | *Category containing security and compliance patterns* | | | **[Policy Generation](#policy-generation)** | Advanced | Operations | Transform compliance requirements into executable Cedar/OPA policy files with AI assistance | Security Sandbox | | **[Security Orchestration](#security-orchestration)** | Intermediate | Workflow | Aggregate multiple security tools and use AI to summarize findings for actionable insights | Security Sandbox | +| **[Centralized Rules](#centralized-rules)** | Advanced | Operations | Enforce organization-wide AI rules through a central Git repository that syncs to standard AI assistant configuration files with automatic language and framework detection | Codified Rules, Progressive Disclosure, Security Orchestration | | **Deployment Automation** | | Operations | *Category containing deployment and pipeline patterns* | | | **Monitoring & Maintenance** | | Operations | *Category containing monitoring and maintenance patterns* | | | **[Baseline Management](#baseline-management)** | Advanced | Operations | Establish intelligent performance baselines and configure monitoring thresholds automatically | Tool Integration | @@ -368,7 +404,7 @@ Starting AI adoption without proper assessment leads to inconsistent practices, **Maturity**: Beginner **Description**: Version and maintain AI coding standards as explicit configuration files that persist across sessions and team members. -**Related Patterns**: [Developer Lifecycle](#developer-lifecycle), [Context Persistence](#context-persistence) +**Related Patterns**: [Developer Lifecycle](#developer-lifecycle), [Context Persistence](#context-persistence), [Progressive Disclosure](#progressive-disclosure), [Event Automation](#event-automation), [Custom Commands](#custom-commands), [Centralized Rules](#centralized-rules) **Standardized Project Structure** ```bash @@ -408,7 +444,7 @@ Each developer maintains their own prompts and preferences, leading to inconsist **Maturity**: Beginner **Description**: Run AI tools in isolated environments without access to secrets or sensitive data to prevent credential leaks and maintain security compliance. -**Related Patterns**: [Security & Compliance Patterns](#security-compliance-patterns), [Codified Rules](#codified-rules) +**Related Patterns**: [Security & Compliance Patterns](#security-compliance-patterns), [Codified Rules](#codified-rules), [Event Automation](#event-automation) **Core Security Implementation** @@ -735,7 +771,7 @@ Specifications use authority levels to resolve conflicts and establish precedenc When requirements conflict, higher authority levels take precedence, enabling clear decision-making for AI implementation. -**Related Patterns**: [Developer Lifecycle](#developer-lifecycle), [Tool Integration](#tool-integration), [Testing Orchestration](experiments/README.md#testing-orchestration), [Observable Development](#observable-development) +**Related Patterns**: [Developer Lifecycle](#developer-lifecycle), [Tool Integration](#tool-integration), [Custom Commands](#custom-commands), [Image Spec](#image-spec), [Testing Orchestration](experiments/README.md#testing-orchestration), [Observable Development](#observable-development) **SpecDriven AI Workflow** @@ -840,6 +876,47 @@ Saving collections of prompts as if they were specifications. Prompts are implem --- +## Image Spec + +**Maturity**: Intermediate +**Description**: Upload images (diagrams, mockups, flows) as primary specifications for AI coding tools to build accurate implementations from visual context. + +**Related Patterns**: [Spec-Driven Development](#spec-driven-development), [Progressive Enhancement](#progressive-enhancement), [Context Optimization](experiments/README.md#context-optimization) + +**Core Implementation** + +Use images as the source of truth for structure and intent, then supplement with minimal text constraints: + +```bash +# 1. Prepare visual specifications +# - architecture.png (components + labeled ports) +# - data-model.png (fields + relationships) +# - ui-mock.png (layout + key interactions) + +# 2. Attach images and provide a minimal build request +cat > build-request.txt << 'EOF' +Build the system from the attached diagrams. +Tech stack: Node.js + Express + PostgreSQL +Start with the User Service exactly as shown. +Include /health endpoints for every service. +EOF + +# 3. Iterate with visual feedback +# - Screenshot the running output +# - Annotate with required changes +# - Re-attach and request the next iteration +``` + +**Complete Implementation** + +See [examples/image-spec/](examples/image-spec/) for prompt templates, diagram checklists, and a repeatable image-first iteration loop. + +**Anti-pattern: Overwhelming Visuals** + +Uploading many diagrams at once without hierarchy or a clear starting point overwhelms context, increases contradictions, and reduces accuracy. Start with one high-level diagram, implement one slice, then add more visuals progressively. + +--- + ## Planned Implementation **Maturity**: Beginner @@ -982,7 +1059,7 @@ Spending excessive time refining plans without moving to implementation, missing **Maturity**: Beginner **Description**: Build complex features through small, deployable iterations rather than big-bang generation. -**Related Patterns**: [Planned Implementation](#planned-implementation), [Developer Lifecycle](#developer-lifecycle), [Constrained Generation](#constrained-generation), [Choice Generation](#choice-generation), [Guided Architecture](#guided-architecture) +**Related Patterns**: [Planned Implementation](#planned-implementation), [Developer Lifecycle](#developer-lifecycle), [Image Spec](#image-spec), [Constrained Generation](#constrained-generation), [Choice Generation](#choice-generation), [Guided Architecture](#guided-architecture) **Examples** Building authentication progressively: @@ -1227,14 +1304,14 @@ Running multiple agents without isolation, shared memory, or conflict resolution **Maturity**: Intermediate **Description**: Manage AI context as a finite resource through structured memory schemas, prompt pattern capture, and session continuity protocols for efficient multi-session development. -**Related Patterns**: [Codified Rules](#codified-rules), [Automated Traceability](#automated-traceability), [Parallel Agents](#parallel-agents) +**Related Patterns**: [Codified Rules](#codified-rules), [Progressive Disclosure](#progressive-disclosure), [Automated Traceability](#automated-traceability), [Parallel Agents](#parallel-agents) **Core Principles** AI context is a finite resource with diminishing returns. Effective context engineering requires: - **Minimal High-Signal Tokens**: Find the smallest set of information that maximizes outcomes - **Just-in-Time Retrieval**: Load context dynamically rather than pre-loading everything -- **Progressive Disclosure**: Explore and discover information as needed, not upfront +- **[Progressive Disclosure](#progressive-disclosure)**: Explore and discover information as needed, not upfront **Structured Memory Schemas** @@ -1377,6 +1454,325 @@ Adding too many constraints ("use exactly 50 lines, 2 methods, no dependencies, --- +## Event Automation + +**Maturity**: Intermediate +**Description**: Execute custom commands automatically at assistant lifecycle events (pre/post tool use, session start, prompt submission) for workflow automation, validation, and policy enforcement. + +**Related Patterns**: [Codified Rules](#codified-rules), [Security Sandbox](#security-sandbox), [Custom Commands](#custom-commands) + +**Core Concept** + +Attach shell commands to AI assistant lifecycle events. Commands receive context via environment variables (file paths, tool names, user prompts) and return exit codes to allow/block/warn. + +**Event Flow Example** + +```mermaid +sequenceDiagram + participant Dev as Developer + participant AI as AI Assistant + participant Pre as PreToolUse Hook + participant Post as PostToolUse Hook + + Dev->>AI: Edit .env file + AI->>Pre: Run security-hook.sh + Pre->>Pre: Check if file is sensitive + Pre-->>AI: Exit 2 (BLOCK) + AI->>Dev: ❌ Blocked: Cannot edit sensitive file + + Dev->>AI: Edit src/api.js + AI->>Pre: Run security-hook.sh + Pre->>Pre: Check if file is sensitive + Pre-->>AI: Exit 0 (Allow) + AI->>AI: Execute file edit + AI->>Post: Run security-hook.sh + Post->>Post: Scan for secrets with gitleaks + alt Secret Found + Post-->>AI: Exit 1 (Warning) + AI->>Dev: ⚠️ Secret detected! Review before committing + else No Secret + Post-->>AI: Exit 0 (Success) + AI->>Dev: ✅ Edit complete + end +``` + +**Simple Security Example** + +Prevent editing sensitive files and scan for secrets: + +```bash +#!/bin/bash +# security-hook.sh + +FILE="$TOOL_INPUT_FILE_PATH" + +# Block .env and credentials files +if echo "$FILE" | grep -E "(\\.env|secrets\\.json|credentials)" > /dev/null; then + echo "❌ Blocked: Cannot edit sensitive file" + exit 2 +fi + +# Scan for hardcoded secrets (requires gitleaks) +if command -v gitleaks > /dev/null; then + if gitleaks detect --no-git --source="$FILE" 2>&1 | grep -q "leaks found"; then + echo "⚠️ Secret detected! Review before committing." + exit 1 + fi +fi + +exit 0 +``` + +**Configuration Example (Claude Code)** + +```json +{ + "hooks": { + "PreToolUse": [{ + "matcher": "Edit", + "hooks": [{"type": "command", "command": "./security-hook.sh"}] + }], + "PostToolUse": [{ + "matcher": "Edit", + "hooks": [{"type": "command", "command": "./security-hook.sh"}] + }] + } +} +``` + +**Common Use Cases** +- Auto-format code after edits (`prettier`, `black`, `gofmt`) +- Block sensitive file modifications +- Log AI interactions for compliance +- Run linters before commits + +**Security Warning** + +Event commands run with full system access. Always review scripts before enabling. Test in isolated environments first. + +**Complete Implementation** + +See [examples/event-automation/](examples/event-automation/) for a working implementation with security scanning and hooks. + +**Anti-pattern: Unchecked Events** + +Running automation from untrusted sources without review exposes your system to malicious code execution and credential theft. Always audit event scripts before installation. + +--- + +## Custom Commands + +**Maturity**: Intermediate +**Description**: Discover and use built-in command vocabularies, then extend them with custom commands that encode domain expertise and sophisticated workflows. + +**Related Patterns**: [Event Automation](#event-automation), [Spec-Driven Development](#spec-driven-development), [Codified Rules](#codified-rules), [Progressive Disclosure](#progressive-disclosure) + +**Core Concept** + +AI coding tools provide built-in commands for common operations and support custom commands (markdown files with AI instructions) for project-specific workflows. Commands are manual/on-demand (invoked like `/refactor`), while events fire automatically (see [Event Automation](#event-automation)). + +**Command Discovery** + +Discover built-in commands first: + +```bash +# Claude Code +/help /model /clear /review + +# Cursor IDE +Cmd+K /edit /chat + +# Gemini CLI +/stats /memory /tools /clear +``` + +| Use Built-in Commands | Create [Custom Commands](#custom-commands) | +|-----------------------|------------------------| +| Generic operations (clear, help, model) | Domain expertise (refactoring, security analysis) | +| Tool features (review, edit) | Project workflows (deploy, implement-spec) | +| Universal commands | Team standards and conventions | + +**Example: Refactoring Assistant** + +Encode Martin Fowler's refactoring catalog for systematic code improvement: + +```markdown +--- +description: Interactive refactoring assistant based on Martin Fowler's refactoring catalog +argument-hint: Optional flags (--smell, --duplicates, --suggest) +--- + +# Refactoring Assistant + +You are helping a developer improve code maintainability by identifying code smells and recommending specific refactoring techniques from Martin Fowler's catalog. + +# Usage +/refactor # Full analysis +/refactor --smell # Code smells only + +# Implementation + +### 1. Code Smell Detection +- Long methods (>20 lines), duplicate code, complex conditionals +- For each: location (file:line), severity, specific refactoring, effort estimate + +### 2. Bloater Detection +- Excessive parameters (>4), data clumps, primitive obsession + +### 3. Refactoring Strategy +1. Name the code smell +2. Recommend technique from Fowler's catalog +3. Show before/after example +4. Estimate maintainability improvement + +Generate step-by-step refactoring plan prioritized by impact. +``` + +**More Examples** + +Additional command examples with detailed implementations: + +- **[Implement-Spec](examples/custom-commands/implement-spec-example.md)** - Spec-driven implementation with TDD and traceability +- **[Security Review](examples/custom-commands/security-review-example.md)** - Multi-layer security analysis (secrets, vulnerabilities, config) +- **[Safe-Refactor](examples/custom-commands/safe-refactor-example.md)** - Safe refactoring with automated testing and rollback +- **[Test Runner](examples/custom-commands/test-example.md)** - Smart test selection with coverage and health monitoring + +**Tool Support** + +```bash +# Claude Code: .claude/commands/*.md +mkdir -p .claude/commands +cp examples/custom-commands/commands/*.md .claude/commands/ + +# Cursor IDE: .cursorrules +cat examples/custom-commands/commands/refactor.md >> .cursorrules + +# Generic: .ai/commands/ (tool-agnostic) +mkdir -p .ai/commands +cp examples/custom-commands/commands/*.md .ai/commands/ +``` + +**Complete Implementation** + +See [examples/custom-commands/](examples/custom-commands/) for ready-to-use commands, configuration files, and setup guide. + +**Anti-pattern: Redundant Commands** + +Creating `/clear` when the tool already provides it. Always discover built-in commands first. + +**Anti-pattern: Shallow Commands** + +```markdown +# Bad: Just wraps shell command +Run: npm run deploy:staging + +# Good: Encodes expertise +1. Verify staging environment health +2. Check for active incidents +3. Review recent commits for risk +4. Run deployment with rollback plan +``` + +**Anti-pattern: Hardcoded Context** + +```markdown +# Bad: Hardcoded values +Deploy to prod-db-instance-1.us-east-1.rds.amazonaws.com + +# Good: Parameterized +Deploy to database: $1 (default: $STAGING_DB) +``` + +--- + +## Progressive Disclosure + +**Maturity**: Intermediate +**Description**: Load AI assistant rules incrementally based on task context rather than bundling all instructions upfront, preventing context bloat and improving instruction-following consistency. + +**Related Patterns**: [Codified Rules](#codified-rules), [Context Persistence](#context-persistence), [Custom Commands](#custom-commands), [Event Automation](#event-automation), [Centralized Rules](#centralized-rules), [Context Optimization](experiments/README.md#context-optimization) + +**Core Problem** + +AI coding assistants already consume part of their context window with built-in system instructions. When a project loads a single, monolithic rules file (hundreds of lines) for every task, instruction-following accuracy drops and irrelevant guidance crowds out what the model needs right now. + +**Implementation Strategy: Three-Tier Rule Architecture** + +Keep a small universal rules file, and load specialized rules only when the task touches the relevant area: + +``` +.ai/ +├── CLAUDE.md # Universal rules only (<60 lines) +├── rules/ # Specialized rules loaded on-demand +│ ├── security/ # secrets, auth, dependencies +│ ├── development/ # api-design, database, testing +│ ├── operations/ # deployment, monitoring, cicd +│ └── architecture/ # patterns, performance +└── prompts/ # Reusable task templates +``` + +**Main Rules File = Router** + +The main file should explicitly tell the assistant what to load based on context: + +```markdown +# AI Development Rules + +# Universal Principles (Always Apply) +- Follow existing patterns in the codebase +- Never commit secrets or credentials +- Run tests after code changes + +# Progressive Disclosure (Context Loading) +- **Security work** (auth/, .env, credentials): Read `.ai/rules/security/` +- **API development** (api/, routes/): Read `.ai/rules/development/api-design.md` +- **Database changes** (migrations/, models/): Read `.ai/rules/development/database.md` +- **Testing** (tests/, specs/): Read `.ai/rules/development/testing.md` +- **CI/CD** (.github/workflows/): Read `.ai/rules/operations/cicd.md` +``` + +**Automatic Loading with Hooks** + +Combine with [Event Automation](#event-automation) to auto-load the right rules before tool use: + +```bash +#!/bin/bash +# .ai/hooks/auto-load-context.sh + +FILE_PATH="$TOOL_INPUT_FILE_PATH" +LOADED_RULES="" + +if echo "$FILE_PATH" | rg -q "(\\.env|credentials|secrets|auth/)"; then + LOADED_RULES="$LOADED_RULES .ai/rules/security/" +fi + +if echo "$FILE_PATH" | rg -q "(api/|routes/|controllers/)"; then + LOADED_RULES="$LOADED_RULES .ai/rules/development/api-design.md" +fi + +if echo "$FILE_PATH" | rg -q "(tests?/|spec/|\\.test\\.|\\.spec\\.)"; then + LOADED_RULES="$LOADED_RULES .ai/rules/development/testing.md" +fi + +if [ -n "$LOADED_RULES" ]; then + echo "AI: Before proceeding, read these files: $LOADED_RULES" +fi +``` + +**Complete Implementation** + +See [examples/progressive-disclosure/](examples/progressive-disclosure/) for templates and a ready-to-adapt rules router + directory layout. + +**Anti-pattern: Bloated Configuration** + +Loading a single, massive rules file for every task wastes context and reduces instruction-following accuracy—especially for small edits that need only a handful of universal rules. + +**Anti-pattern: Missing Guidance** + +Creating specialized rule files but never documenting when/how to load them forces humans to remember the routing and prevents consistent, automated context loading. + +--- + ## Atomic Decomposition **Maturity**: Intermediate @@ -2022,7 +2418,7 @@ Operations patterns focus on CI/CD, security, compliance, and production managem **Maturity**: Advanced **Description**: Transform compliance requirements into executable policy files with AI assistance, ensuring regulatory requirements become testable code. -**Related Patterns**: [Security Sandbox](#security-sandbox), [Codified Rules](#codified-rules) +**Related Patterns**: [Security Sandbox](#security-sandbox), [Codified Rules](#codified-rules), [Centralized Rules](#centralized-rules) ```bash # Transform compliance requirements into executable policies @@ -2049,7 +2445,7 @@ Hand-coding policies from written requirements introduces inconsistencies and in **Maturity**: Intermediate **Description**: Aggregate multiple security tools and use AI to summarize findings for actionable insights, reducing alert fatigue while maintaining security rigor. -**Related Patterns**: [Policy Generation](#policy-generation) +**Related Patterns**: [Policy Generation](#policy-generation), [Centralized Rules](#centralized-rules) ```bash # Orchestrate multiple security tools @@ -2073,6 +2469,58 @@ Posting every low-severity finding buries real issues and frustrates developers. --- +### Centralized Rules + +**Maturity**: Advanced +**Description**: Enforce organization-wide AI rules through a central Git repository that syncs language- and framework-specific guidance into standard assistant configuration files. + +**Related Patterns**: [Codified Rules](#codified-rules), [Progressive Disclosure](#progressive-disclosure), [Security Orchestration](#security-orchestration) + +**Core Implementation** + +**Sync-based Architecture** (Recommended): + +``` +Central Rules Repository (Git) + ├── base/universal-rules.md + ├── languages/ (python.md, typescript.md, go.md) + └── frameworks/ (react.md, django.md, fastapi.md) + ↓ + [sync-ai-rules.sh] + ↓ + Project Repository + ├── CLAUDE.md (auto-generated) + ├── AGENTS.md (auto-generated) + └── .cursorrules (auto-generated) +``` + +**How it works**: +1. A central repository stores organization rules organized by language/framework. +2. A sync script detects the project language/framework (from files and dependencies). +3. The script generates standard configuration files that common assistants read automatically. + +**Key benefits**: +- ✅ Works with existing AI tools (no gateway required) +- ✅ Offline-friendly after initial sync +- ✅ Version-controlled and auditable in Git +- ✅ Language-aware via auto-detection + +**Alternative: Gateway Strategy** (advanced use cases) + +For organizations needing request/response filtering, policy enforcement, or usage logging, use the gateway approach: +- [Gateway Strategy](examples/centralized-rules/gateway-strategy/README-GATEWAY.md) + +**Complete Implementation** + +- [Sync Strategy](examples/centralized-rules/sync-strategy/) - Simple Git-based sync (recommended) +- [Gateway Strategy](examples/centralized-rules/gateway-strategy/README-GATEWAY.md) - Central policy + logging + filters + +**Anti-pattern: Scattered Configuration** + +Copying AI rules into every repository without a central source causes drift, inconsistent enforcement, and manual update toil across teams. + +--- + diff --git a/docs/ai-development-best-practices.md b/docs/ai-development-best-practices.md index d7154d4..42e55a8 100644 --- a/docs/ai-development-best-practices.md +++ b/docs/ai-development-best-practices.md @@ -56,7 +56,7 @@ A canonical, enumerated list of best practices derived from comprehensive analys 22. **Context Optimization**: Match AI tool selection to task complexity using [Context Optimization](../experiments/README.md#context-optimization) and defined criteria: simple models for queries <500 tokens, complex models for architecture decisions >2000 tokens. -23. **Image Spec**: Use diagrams, mockups, and flows as primary specifications for complex needs using [Image Spec](../experiments/README.md#image-spec), supplemented with structured text for precise details. +23. **Image Spec**: Use diagrams, mockups, and flows as primary specifications for complex needs using [Image Spec](../README.md#image-spec), supplemented with structured text for precise details. 24. **Version Knowledge Assets**: Treat AI development knowledge as code with semantic versioning, peer review processes, and automated quality checks. @@ -66,9 +66,9 @@ A canonical, enumerated list of best practices derived from comprehensive analys 26. **Smart Defaults with Extensibility**: Design AI development tools that work perfectly with no configuration while supporting advanced customization options. -27. **Self-Documenting Commands**: Include comprehensive built-in help with usage patterns, examples, and parameter explanations in every AI development tool using [Custom Commands](../experiments/README.md#custom-commands). +27. **Self-Documenting Commands**: Include comprehensive built-in help with usage patterns, examples, and parameter explanations in every AI development tool using [Custom Commands](../README.md#custom-commands). -28. **Hooks-Based Governance**: Implement flexible hook systems for automated monitoring, logging, and policy enforcement at critical development workflow points using [Event Automation](../experiments/README.md#event-automation). +28. **Hooks-Based Governance**: Implement flexible hook systems for automated monitoring, logging, and policy enforcement at critical development workflow points using [Event Automation](../README.md#event-automation). 29. **Modular Command Architecture**: Organize AI tools into clear categories with well-defined scopes (project-specific vs. machine-wide) for flexible workflows. diff --git a/experiments/examples/centralized-rules/README.md b/examples/centralized-rules/README.md similarity index 100% rename from experiments/examples/centralized-rules/README.md rename to examples/centralized-rules/README.md diff --git a/experiments/examples/centralized-rules/gateway-strategy/README-GATEWAY.md b/examples/centralized-rules/gateway-strategy/README-GATEWAY.md similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/README-GATEWAY.md rename to examples/centralized-rules/gateway-strategy/README-GATEWAY.md diff --git a/experiments/examples/centralized-rules/gateway-strategy/ai-dev-cli/package.json b/examples/centralized-rules/gateway-strategy/ai-dev-cli/package.json similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/ai-dev-cli/package.json rename to examples/centralized-rules/gateway-strategy/ai-dev-cli/package.json diff --git a/experiments/examples/centralized-rules/gateway-strategy/ai-dev-cli/src/cli.ts b/examples/centralized-rules/gateway-strategy/ai-dev-cli/src/cli.ts similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/ai-dev-cli/src/cli.ts rename to examples/centralized-rules/gateway-strategy/ai-dev-cli/src/cli.ts diff --git a/experiments/examples/centralized-rules/gateway-strategy/ai-gateway/package.json b/examples/centralized-rules/gateway-strategy/ai-gateway/package.json similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/ai-gateway/package.json rename to examples/centralized-rules/gateway-strategy/ai-gateway/package.json diff --git a/experiments/examples/centralized-rules/gateway-strategy/ai-gateway/src/claudeClient.ts b/examples/centralized-rules/gateway-strategy/ai-gateway/src/claudeClient.ts similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/ai-gateway/src/claudeClient.ts rename to examples/centralized-rules/gateway-strategy/ai-gateway/src/claudeClient.ts diff --git a/experiments/examples/centralized-rules/gateway-strategy/ai-gateway/src/server.ts b/examples/centralized-rules/gateway-strategy/ai-gateway/src/server.ts similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/ai-gateway/src/server.ts rename to examples/centralized-rules/gateway-strategy/ai-gateway/src/server.ts diff --git a/experiments/examples/centralized-rules/gateway-strategy/org-ai-client/package.json b/examples/centralized-rules/gateway-strategy/org-ai-client/package.json similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/org-ai-client/package.json rename to examples/centralized-rules/gateway-strategy/org-ai-client/package.json diff --git a/experiments/examples/centralized-rules/gateway-strategy/org-ai-client/src/index.ts b/examples/centralized-rules/gateway-strategy/org-ai-client/src/index.ts similarity index 100% rename from experiments/examples/centralized-rules/gateway-strategy/org-ai-client/src/index.ts rename to examples/centralized-rules/gateway-strategy/org-ai-client/src/index.ts diff --git a/experiments/examples/centralized-rules/sync-strategy/create-central-repo.sh b/examples/centralized-rules/sync-strategy/create-central-repo.sh similarity index 100% rename from experiments/examples/centralized-rules/sync-strategy/create-central-repo.sh rename to examples/centralized-rules/sync-strategy/create-central-repo.sh diff --git a/experiments/examples/centralized-rules/sync-strategy/example-central-repo/base/universal-rules.md b/examples/centralized-rules/sync-strategy/example-central-repo/base/universal-rules.md similarity index 100% rename from experiments/examples/centralized-rules/sync-strategy/example-central-repo/base/universal-rules.md rename to examples/centralized-rules/sync-strategy/example-central-repo/base/universal-rules.md diff --git a/experiments/examples/centralized-rules/sync-strategy/example-central-repo/frameworks/react.md b/examples/centralized-rules/sync-strategy/example-central-repo/frameworks/react.md similarity index 100% rename from experiments/examples/centralized-rules/sync-strategy/example-central-repo/frameworks/react.md rename to examples/centralized-rules/sync-strategy/example-central-repo/frameworks/react.md diff --git a/experiments/examples/centralized-rules/sync-strategy/example-central-repo/languages/python.md b/examples/centralized-rules/sync-strategy/example-central-repo/languages/python.md similarity index 100% rename from experiments/examples/centralized-rules/sync-strategy/example-central-repo/languages/python.md rename to examples/centralized-rules/sync-strategy/example-central-repo/languages/python.md diff --git a/experiments/examples/centralized-rules/sync-strategy/sync-ai-rules.sh b/examples/centralized-rules/sync-strategy/sync-ai-rules.sh similarity index 100% rename from experiments/examples/centralized-rules/sync-strategy/sync-ai-rules.sh rename to examples/centralized-rules/sync-strategy/sync-ai-rules.sh diff --git a/experiments/examples/custom-commands/README.md b/examples/custom-commands/README.md similarity index 100% rename from experiments/examples/custom-commands/README.md rename to examples/custom-commands/README.md diff --git a/experiments/examples/custom-commands/claude-settings.json b/examples/custom-commands/claude-settings.json similarity index 100% rename from experiments/examples/custom-commands/claude-settings.json rename to examples/custom-commands/claude-settings.json diff --git a/experiments/examples/custom-commands/commands/implement-spec.md b/examples/custom-commands/commands/implement-spec.md similarity index 100% rename from experiments/examples/custom-commands/commands/implement-spec.md rename to examples/custom-commands/commands/implement-spec.md diff --git a/experiments/examples/custom-commands/commands/refactor.md b/examples/custom-commands/commands/refactor.md similarity index 100% rename from experiments/examples/custom-commands/commands/refactor.md rename to examples/custom-commands/commands/refactor.md diff --git a/experiments/examples/custom-commands/commands/safe-refactor.md b/examples/custom-commands/commands/safe-refactor.md similarity index 100% rename from experiments/examples/custom-commands/commands/safe-refactor.md rename to examples/custom-commands/commands/safe-refactor.md diff --git a/experiments/examples/custom-commands/commands/security-review.md b/examples/custom-commands/commands/security-review.md similarity index 100% rename from experiments/examples/custom-commands/commands/security-review.md rename to examples/custom-commands/commands/security-review.md diff --git a/experiments/examples/custom-commands/commands/test.md b/examples/custom-commands/commands/test.md similarity index 100% rename from experiments/examples/custom-commands/commands/test.md rename to examples/custom-commands/commands/test.md diff --git a/experiments/examples/custom-commands/implement-spec-example.md b/examples/custom-commands/implement-spec-example.md similarity index 94% rename from experiments/examples/custom-commands/implement-spec-example.md rename to examples/custom-commands/implement-spec-example.md index 667b4a7..cca09cd 100644 --- a/experiments/examples/custom-commands/implement-spec-example.md +++ b/examples/custom-commands/implement-spec-example.md @@ -79,5 +79,5 @@ EOF ## Related Patterns -- [Spec-Driven Development](../../../README.md#spec-driven-development) -- [Automated Traceability](../../../README.md#automated-traceability) +- [Spec-Driven Development](../../README.md#spec-driven-development) +- [Automated Traceability](../../README.md#automated-traceability) diff --git a/experiments/examples/custom-commands/safe-refactor-example.md b/examples/custom-commands/safe-refactor-example.md similarity index 94% rename from experiments/examples/custom-commands/safe-refactor-example.md rename to examples/custom-commands/safe-refactor-example.md index d1d3b7a..1e4a111 100644 --- a/experiments/examples/custom-commands/safe-refactor-example.md +++ b/examples/custom-commands/safe-refactor-example.md @@ -92,5 +92,5 @@ Automatic approval if ALL conditions met: ## Related Patterns -- [Guided Refactoring](../../../README.md#guided-refactoring) -- [Testing Orchestration](../../README.md#testing-orchestration) +- [Guided Refactoring](../../README.md#guided-refactoring) +- [Testing Orchestration](../../experiments/README.md#testing-orchestration) diff --git a/experiments/examples/custom-commands/security-review-example.md b/examples/custom-commands/security-review-example.md similarity index 94% rename from experiments/examples/custom-commands/security-review-example.md rename to examples/custom-commands/security-review-example.md index 94dd3d7..27bb2b7 100644 --- a/experiments/examples/custom-commands/security-review-example.md +++ b/examples/custom-commands/security-review-example.md @@ -95,5 +95,5 @@ if (!API_KEY) throw new Error("STRIPE_API_KEY required") ## Related Patterns -- [Security Orchestration](../../../README.md#security-orchestration) -- [Security Sandbox](../../../README.md#security-sandbox) +- [Security Orchestration](../../README.md#security-orchestration) +- [Security Sandbox](../../README.md#security-sandbox) diff --git a/experiments/examples/custom-commands/test-example.md b/examples/custom-commands/test-example.md similarity index 94% rename from experiments/examples/custom-commands/test-example.md rename to examples/custom-commands/test-example.md index 6d05ad5..9fa5675 100644 --- a/experiments/examples/custom-commands/test-example.md +++ b/examples/custom-commands/test-example.md @@ -104,5 +104,5 @@ git diff --name-only HEAD~1 HEAD ## Related Patterns -- [Testing Orchestration](../../README.md#testing-orchestration) -- [Suite Health](../../README.md#suite-health) +- [Testing Orchestration](../../experiments/README.md#testing-orchestration) +- [Suite Health](../../experiments/README.md#suite-health) diff --git a/experiments/examples/event-automation/README.md b/examples/event-automation/README.md similarity index 100% rename from experiments/examples/event-automation/README.md rename to examples/event-automation/README.md diff --git a/experiments/examples/event-automation/claude-settings.json b/examples/event-automation/claude-settings.json similarity index 100% rename from experiments/examples/event-automation/claude-settings.json rename to examples/event-automation/claude-settings.json diff --git a/experiments/examples/event-automation/security-hook.sh b/examples/event-automation/security-hook.sh similarity index 100% rename from experiments/examples/event-automation/security-hook.sh rename to examples/event-automation/security-hook.sh diff --git a/examples/image-spec/README.md b/examples/image-spec/README.md new file mode 100644 index 0000000..92acee3 --- /dev/null +++ b/examples/image-spec/README.md @@ -0,0 +1,28 @@ +# Image Spec Example + +This example provides a repeatable, image-first workflow for the [Image Spec](../../README.md#image-spec) pattern: use diagrams and mockups as primary specifications, then iterate with annotated visuals. + +## Workflow + +1. Create a **single** high-level diagram (architecture, UI mock, or flow) with labels and constraints (ports, component names, state transitions). +2. Attach the image and provide a short prompt that clarifies only what the image cannot (tech stack, scope, constraints). +3. Run the generated result, capture a screenshot, and annotate what’s missing or incorrect. +4. Re-attach the annotated image and iterate on one slice at a time. + +## Recommended Image Set + +- `architecture.png`: components + boundaries + ports +- `data-model.png`: fields + relationships + example payloads +- `ui-mock.png`: layout + key interactions +- `flow.png`: sequence of steps + decision points + +## Prompt Template + +```text +Build the system from the attached images. +Tech stack: +Scope: +Constraints: +Output: code + tests + a short runbook +``` + diff --git a/examples/progressive-disclosure/README.md b/examples/progressive-disclosure/README.md new file mode 100644 index 0000000..0b86c54 --- /dev/null +++ b/examples/progressive-disclosure/README.md @@ -0,0 +1,27 @@ +# Progressive Disclosure Example + +This example provides a tool-agnostic starter layout for implementing the [Progressive Disclosure](../../README.md#progressive-disclosure) pattern in a real repository. + +## Goal + +Keep a small, universal rules file that applies to every task, and load specialized rules only when the work context requires them (security, API design, testing, CI/CD, etc.). + +## Starter Layout + +```text +.ai/ +├── CLAUDE.md # Universal rules + routing hints (<60 lines) +├── rules/ +│ ├── security/ # secrets, auth, dependencies +│ ├── development/ # api-design, database, testing +│ ├── operations/ # deployment, monitoring, cicd +│ └── architecture/ # patterns, performance +└── prompts/ # reusable task templates +``` + +## Suggested Workflow + +1. Keep `.ai/CLAUDE.md` minimal and explicit about **when** to load specialized rules. +2. Add small, focused rule files under `.ai/rules/` (aim for <100 lines each). +3. Optionally combine with [Event Automation](../../README.md#event-automation) to auto-load the relevant rules before edits, writes, or test runs. + diff --git a/experiments/README.md b/experiments/README.md index 8e95c53..f5227e3 100644 --- a/experiments/README.md +++ b/experiments/README.md @@ -36,12 +36,7 @@ These experimental patterns extend the core AI development patterns with advance | **[ChatOps Security](#chatops-security)** | Beginner | Operations | Deploy security scanning capabilities through chat commands for immediate feedback | Security Orchestration | | **[Evidence Automation](#evidence-automation)** | Advanced | Operations | Generate audit evidence matrices from logs and configuration changes automatically | Security Orchestration | | **[Context Optimization](#context-optimization)** | Advanced | Development | Match AI tool selection to task complexity and optimize cost/performance trade-offs | Progressive Enhancement | -| **[Image Spec](#image-spec)** | Intermediate | Development | Upload images (diagrams, mockups, flows) as primary specifications for AI coding tools to build accurate implementations from visual context | Spec-Driven Development, Progressive Enhancement, Context Optimization | -| **[Event Automation](#event-automation)** | Intermediate | Development | Execute custom commands automatically at specific lifecycle events in AI coding assistants to enforce policies and automate workflows | Codified Rules, Security Sandbox | -| **[Custom Commands](#custom-commands)** | Intermediate | Development | Discover and use built-in command vocabularies, then extend them with custom commands that encode domain expertise and project-specific workflows | Event Automation, Spec-Driven Development | -| **[Progressive Disclosure](#progressive-disclosure)** | Intermediate | Development | Load AI assistant rules incrementally based on task context to prevent instruction saturation and maintain consistency | Codified Rules, Context Optimization | | **[Asynchronous Research](#asynchronous-research)** | Intermediate | Development | Use fire-and-forget coding agents in dedicated repositories to conduct autonomous code investigations that prove technical feasibility through executable experiments | Parallel Agents, Context Persistence, Choice Generation | -| **[Centralized Rules](#centralized-rules)** | Advanced | Operations | Enforce organization-wide AI rules through a central gateway service or shared SDK library rather than distributing configuration files | Codified Rules, Policy Generation, Security Orchestration | --- @@ -404,770 +399,6 @@ Running parallel agents without proper isolation, conflict detection, or sync po Always using the most powerful (expensive) AI model for simple tasks wastes resources and increases latency for routine operations. --- - -### Image Spec - -**Maturity**: Intermediate -**Description**: Upload images (diagrams, mockups, flows) as primary specifications for AI coding tools to build accurate implementations from visual context. - -**Related Patterns**: [Spec-Driven Development](../README.md#spec-driven-development), [Progressive Enhancement](../README.md#progressive-enhancement), [Context Optimization](#context-optimization) - -#### Core Implementation - -```bash -# 1. Prepare visual specifications -# Create architecture diagram showing microservices structure -# Save as: architecture.png with labeled components: -# - API Gateway (port 8080) -# - User Service (port 3001) -# - Order Service (port 3002) -# - Payment Service (port 3003) -# - PostgreSQL databases per service -# - RabbitMQ message bus connections - -# 2. Upload to AI coding tool with minimal context -# Example prompt for Claude Code: -cat > build-request.txt << 'EOF' -Build this microservices architecture from the attached diagram. -Tech stack: Node.js, Express, PostgreSQL, RabbitMQ -Start with the User Service following the exact structure shown. -Include health check endpoints at /health for each service. -EOF - -# 3. Iterate with visual feedback -# After initial generation, screenshot the running system -# Annotate screenshot with required changes -# Example: mark missing authentication flow in red -# Re-upload annotated screenshot with refinement request - -# 4. Structure for complex UIs -# For dashboard implementation: -# - dashboard-layout.png (grid measurements, component names) -# - dashboard-interactions.png (click flows, state changes) -# - data-model.png (API responses, field mappings) - -# Upload sequence with prompt: -"Implement this dashboard using React and Tailwind. -Match the layout from dashboard-layout.png exactly. -Use the interaction flows from dashboard-interactions.png. -Mock data structure should follow data-model.png." -``` - -#### Anti-pattern: Overwhelming Visuals - -**Problem**: Uploading many diagrams at once (e.g., 15+) without structure or context - -```bash -# Wrong approach - overwhelming context -"Here are all my diagrams. Build the system." -# Uploads: erd.png, architecture.png, flow1.png, flow2.png, -# ui1.png, ui2.png, deployment.png, sequence1.png... - -# Why it fails: -# - AI loses focus trying to parse everything -# - Contradictions between diagrams cause confusion -# - Exceeds useful context window -# - No clear starting point - -# Correct approach: -# Upload progressively with clear hierarchy -"1. Start with this high-level architecture (architecture.png) -2. Focus on User Service first -3. I'll provide UI mockups after core services work" -``` - ---- - -### Event Automation - -**Maturity**: Intermediate -**Description**: Execute custom commands automatically at specific lifecycle events (before/after file operations, session start, prompt submission) for workflow automation, validation, and policy enforcement. - -**Related Patterns**: [Codified Rules](../README.md#codified-rules), [Security Sandbox](../README.md#security-sandbox) - -**Core Concept** - -Attach shell commands to AI assistant lifecycle events. Commands receive context via environment variables (file paths, tool names, user prompts) and return exit codes: `0` (allow), `2` (block), or other (warn). - -**Event Flow Example** - -```mermaid -sequenceDiagram - participant Dev as Developer - participant AI as AI Assistant - participant Pre as PreToolUse Hook - participant Post as PostToolUse Hook - - Dev->>AI: Edit .env file - AI->>Pre: Run security-hook.sh - Pre->>Pre: Check if file is sensitive - Pre-->>AI: Exit 2 (BLOCK) - AI->>Dev: ❌ Blocked: Cannot edit sensitive file - - Dev->>AI: Edit src/api.js - AI->>Pre: Run security-hook.sh - Pre->>Pre: Check if file is sensitive - Pre-->>AI: Exit 0 (Allow) - AI->>AI: Execute file edit - AI->>Post: Run security-hook.sh - Post->>Post: Scan for secrets with gitleaks - alt Secret Found - Post-->>AI: Exit 1 (Warning) - AI->>Dev: ⚠️ Secret detected! Review before committing - else No Secret - Post-->>AI: Exit 0 (Success) - AI->>Dev: ✅ Edit complete - end -``` - -**Simple Security Example** - -Prevent editing sensitive files and scan for secrets: - -```bash -#!/bin/bash -# security-hook.sh - -FILE="$TOOL_INPUT_FILE_PATH" - -# Block .env and credentials files -if echo "$FILE" | grep -E "(\.env|secrets\.json|credentials)" > /dev/null; then - echo "❌ Blocked: Cannot edit sensitive file" - exit 2 -fi - -# Scan for hardcoded secrets (requires gitleaks) -if command -v gitleaks > /dev/null; then - if gitleaks detect --no-git --source="$FILE" 2>&1 | grep -q "leaks found"; then - echo "⚠️ Secret detected! Review before committing." - exit 1 - fi -fi - -exit 0 -``` - -**Configuration Example (Claude Code)** - -```json -{ - "hooks": { - "PreToolUse": [{ - "matcher": "Edit", - "hooks": [{"type": "command", "command": "./security-hook.sh"}] - }], - "PostToolUse": [{ - "matcher": "Edit", - "hooks": [{"type": "command", "command": "./security-hook.sh"}] - }] - } -} -``` - -**Common Use Cases** -- Auto-format code after edits (`prettier`, `black`, `gofmt`) -- Block sensitive file modifications -- Log AI interactions for compliance -- Run linters before commits - -**Security Warning** - -Event commands run with full system access. Always review scripts before enabling. Test in isolated environments first. - -**Complete Example** - -See [examples/event-automation/](examples/event-automation/) for a working implementation with security scanning and hooks. - -**Anti-pattern: Unchecked Events** - -Running automation from untrusted sources without review exposes your system to malicious code execution and credential theft. Always audit event scripts before installation. - ---- - -### Custom Commands - -**Maturity**: Intermediate -**Description**: Discover and use built-in command vocabularies, then extend them with custom commands that encode domain expertise and sophisticated workflows. - -**Related Patterns**: [Event Automation](#event-automation), [Spec-Driven Development](../README.md#spec-driven-development), [Codified Rules](../README.md#codified-rules) - -**Core Concept** - -AI coding tools provide built-in commands for common operations and support custom commands (markdown files with AI instructions) for project-specific workflows. Commands are manual/on-demand (invoked like `/refactor`), while events fire automatically (see [Event Automation](#event-automation)). - -**Command Discovery** - -Discover built-in commands first: - -```bash -# Claude Code -/help /model /clear /review - -# Cursor IDE -Cmd+K /edit /chat - -# Gemini CLI -/stats /memory /tools /clear -``` - -| Use Built-in Commands | Create Custom Commands | -|-----------------------|------------------------| -| Generic operations (clear, help, model) | Domain expertise (refactoring, security analysis) | -| Tool features (review, edit) | Project workflows (deploy, implement-spec) | -| Universal commands | Team standards and conventions | - -**Example: Refactoring Assistant** - -Encode Martin Fowler's refactoring catalog for systematic code improvement: - -```markdown ---- -description: Interactive refactoring assistant based on Martin Fowler's refactoring catalog -argument-hint: Optional flags (--smell, --duplicates, --suggest) ---- - -# Refactoring Assistant - -You are helping a developer improve code maintainability by identifying code smells and recommending specific refactoring techniques from Martin Fowler's catalog. - -## Usage -/refactor # Full analysis -/refactor --smell # Code smells only - -## Implementation - -### 1. Code Smell Detection -- Long methods (>20 lines), duplicate code, complex conditionals -- For each: location (file:line), severity, specific refactoring, effort estimate - -### 2. Bloater Detection -- Excessive parameters (>4), data clumps, primitive obsession - -### 3. Refactoring Strategy -1. Name the code smell -2. Recommend technique from Fowler's catalog -3. Show before/after example -4. Estimate maintainability improvement - -Generate step-by-step refactoring plan prioritized by impact. -``` - -**More Examples** - -Additional command examples with detailed implementations: - -- **[Implement-Spec](examples/custom-commands/implement-spec-example.md)** - Spec-driven implementation with TDD and traceability -- **[Security Review](examples/custom-commands/security-review-example.md)** - Multi-layer security analysis (secrets, vulnerabilities, config) -- **[Safe-Refactor](examples/custom-commands/safe-refactor-example.md)** - Safe refactoring with automated testing and rollback -- **[Test Runner](examples/custom-commands/test-example.md)** - Smart test selection with coverage and health monitoring - -**Tool Support** - -```bash -# Claude Code: .claude/commands/*.md -mkdir -p .claude/commands -cp commands/refactor.md .claude/commands/ - -# Cursor IDE: .cursorrules -cat commands/refactor.md >> .cursorrules - -# Generic: .ai/commands/ (tool-agnostic) -mkdir -p .ai/commands -``` - -**Complete Implementation** - -See [examples/custom-commands/](examples/custom-commands/) for ready-to-use commands, configuration files, and setup guide. - -**Anti-pattern: Redundant Commands** - -Creating `/clear` when the tool already provides it. Always discover built-in commands first. - -**Anti-pattern: Shallow Commands** - -```markdown -# Bad: Just wraps shell command -Run: npm run deploy:staging - -# Good: Encodes expertise -1. Verify staging environment health -2. Check for active incidents -3. Review recent commits for risk -4. Run deployment with rollback plan -``` - -**Anti-pattern: Hardcoded Context** - -```markdown -# Bad: Hardcoded values -Deploy to prod-db-instance-1.us-east-1.rds.amazonaws.com - -# Good: Parameterized -Deploy to database: $1 (default: $STAGING_DB) -``` - ---- - -### Progressive Disclosure - -**Maturity**: Intermediate -**Description**: Load AI assistant rules incrementally based on task context rather than bundling all instructions upfront, preventing context bloat and maintaining instruction-following consistency across any AI coding assistant (Claude Code, Cursor, Codex, Gemini, etc.). - -**Related Patterns**: [Codified Rules](../README.md#codified-rules), [Context Optimization](#context-optimization), [Custom Commands](#custom-commands), [Event Automation](#event-automation) - -**Source**: HumanLayer, "Context engineering: Why your CLAUDE.md is probably too long" (research on instruction limits and context optimization) - -#### Core Problem - -**Instruction saturation**: LLMs can follow ~150-200 instructions with reasonable consistency. AI coding assistants' system prompts already contain ~50 instructions, leaving ~100-150 for your project rules. Loading all rules every session causes: - -- Linear decay in instruction-following accuracy -- Context window waste on irrelevant rules -- Cognitive overload for the AI -- Slower response times from processing unnecessary context - -**Example of bloat**: A 500-line configuration file (CLAUDE.md, AGENTS.md, .cursorrules, etc.) with security rules, deployment procedures, architecture patterns, testing standards, code style guides, API conventions, database migration rules, monitoring setup, and team workflows—but only 10% is relevant to any single task. - -#### Implementation Strategy - -**Three-tier rule architecture:** - -This pattern works with any AI assistant configuration file. Examples shown use CLAUDE.md, but apply equally to .cursorrules (Cursor), AGENTS.md, or other AI coding assistant configuration files (Codex, Gemini, etc.). - -``` -.ai/ -├── CLAUDE.md # Main rules file: Universal rules only (<60 lines) -│ # (or AGENTS.md, .cursorrules, etc.) -├── rules/ # Specialized rules loaded on-demand -│ ├── security/ -│ │ ├── secrets.md # Load when: editing .env, credentials -│ │ ├── dependencies.md # Load when: package.json, requirements.txt -│ │ └── authentication.md # Load when: auth/ directory work -│ ├── development/ -│ │ ├── api-design.md # Load when: working in api/ or routes/ -│ │ ├── database.md # Load when: migrations/, models/ -│ │ ├── testing.md # Load when: tests/ or spec files -│ │ └── frontend.md # Load when: components/, styles/ -│ ├── operations/ -│ │ ├── deployment.md # Load when: Dockerfile, k8s/, terraform/ -│ │ ├── monitoring.md # Load when: logs, metrics, alerts -│ │ └── cicd.md # Load when: .github/workflows/ -│ └── architecture/ -│ ├── patterns.md # Load when: major refactoring -│ └── performance.md # Load when: optimization tasks -└── prompts/ # Reusable task templates - ├── implement-feature.md - └── fix-bug.md -``` - -#### Main Rules File - -**Keep it minimal** - only universally applicable rules. - -This example uses CLAUDE.md, but the same structure applies to AGENTS.md, .cursorrules, or any AI assistant configuration file: - -```markdown -# AI Development Rules - -## Universal Principles (Always Apply) - -### Code Quality -- Write clear, self-documenting code with meaningful names -- Follow existing patterns in the codebase -- Include error handling for all external calls - -### Communication -- Ask clarifying questions before major changes -- Explain non-obvious decisions in comments -- Reference task/issue numbers in commits - -### Safety -- Never commit secrets, API keys, or credentials -- Run tests before committing code changes -- Check git diff before every commit - -### Context Loading (Progressive Disclosure) -When working in specific areas, load specialized rules: - -- **Security work** (auth/, .env, credentials): Read .ai/rules/security/ -- **API development** (api/, routes/): Read .ai/rules/development/api-design.md -- **Database changes** (migrations/, models/): Read .ai/rules/development/database.md -- **Testing** (tests/, specs/): Read .ai/rules/development/testing.md -- **Frontend** (components/, styles/): Read .ai/rules/development/frontend.md -- **Deployment** (Dockerfile, k8s/): Read .ai/rules/operations/deployment.md -- **CI/CD** (.github/workflows/): Read .ai/rules/operations/cicd.md - -**How to load**: "Before proceeding, read the relevant rules from .ai/rules/[category]/" -``` - -**Key insight**: The main file becomes a **router** that tells the AI which specialized rules to load based on context. - -#### Specialized Rules Examples - -**Example: .ai/rules/security/secrets.md** - -```markdown -# Security: Secret Management Rules - -## When to Load -Load this file when working with: -- .env files or environment variables -- credentials.json, secrets.yaml, config files with sensitive data -- Authentication tokens or API keys -- Deployment configurations with passwords - -## Rules - -### Secret Detection -1. Run `gitleaks detect --no-git --source=` before committing -2. Block commits containing patterns: AWS keys, JWT tokens, database passwords -3. Use environment variable references, never hardcoded values - -### Environment Variables -# CORRECT: Reference variables -DATABASE_URL=${DATABASE_URL} -API_KEY=${STRIPE_API_KEY} - -# WRONG: Hardcoded secrets -DATABASE_URL=postgresql://admin:password123@prod-db.com -API_KEY=sk_live_abc123xyz - -### Credential Files -- NEVER edit .env files directly -- Use .env.example templates with placeholder values -- All secrets go in secret management (AWS Secrets Manager, 1Password) - -### Validation -Before committing, verify: -# No secrets in staged files -git diff --cached | gitleaks detect --no-git --verbose --source=/dev/stdin - -# No .env files staged -git diff --cached --name-only | grep -E "(\.env$|credentials)" && exit 1 -``` - -**Example: .ai/rules/development/api-design.md** - -```markdown -# Development: API Design Rules - -## When to Load -Load this file when working with: -- api/, routes/, controllers/ directories -- HTTP endpoint implementation -- API contract changes - -## Rules - -### RESTful Design -- Use standard HTTP methods: GET (read), POST (create), PUT/PATCH (update), DELETE -- Plural nouns for resources: `/users`, `/orders`, not `/getUser` -- Nest related resources: `/users/:id/orders` for user-specific orders - -### Response Format -All API responses must use this structure: -{ - "success": true, - "data": { ... }, - "error": null, - "meta": { - "timestamp": "2025-01-15T10:30:00Z", - "request_id": "abc-123" - } -} - -### Error Handling -// CORRECT: Structured errors -res.status(404).json({ - success: false, - data: null, - error: { - code: "USER_NOT_FOUND", - message: "User with ID 123 not found", - details: { user_id: 123 } - } -}); - -// WRONG: Generic errors -res.status(500).send("Error"); - -### Validation -- Validate all inputs at API boundary -- Return 400 Bad Request with specific validation errors -- Document all endpoints in OpenAPI/Swagger spec -``` - -#### Decision Framework for Rule Loading - -```mermaid -graph TD - A[AI Assistant Receives Task] --> B{Analyze Task Context} - - B -->|File paths mentioned| C[Extract directory/file patterns] - B -->|Task description keywords| D[Identify domain area] - - C --> E{Match Pattern} - D --> E - - E -->|auth/, .env, credentials| F[Load security/ rules] - E -->|api/, routes/| G[Load api-design.md] - E -->|migrations/, models/| H[Load database.md] - E -->|tests/, spec/| I[Load testing.md] - E -->|components/, styles/| J[Load frontend.md] - E -->|Dockerfile, k8s/| K[Load deployment.md] - E -->|.github/workflows/| L[Load cicd.md] - E -->|No specific pattern| M[Use main rules only] - - F --> N[Execute Task with Specialized Context] - G --> N - H --> N - I --> N - J --> N - K --> N - L --> N - M --> N -``` - -#### Automatic Loading with Event Hooks - -Combine Progressive Disclosure with [Event Automation](#event-automation) for automatic context loading: - -```bash -#!/bin/bash -# .ai/hooks/auto-load-context.sh -# Runs before AI tool use to automatically load relevant rules - -FILE_PATH="$TOOL_INPUT_FILE_PATH" -LOADED_RULES="" - -# Security context -if echo "$FILE_PATH" | grep -E "(\.env|credentials|secrets|auth/)" > /dev/null; then - LOADED_RULES="$LOADED_RULES .ai/rules/security/" -fi - -# API development context -if echo "$FILE_PATH" | grep -E "(api/|routes/|controllers/)" > /dev/null; then - LOADED_RULES="$LOADED_RULES .ai/rules/development/api-design.md" -fi - -# Database context -if echo "$FILE_PATH" | grep -E "(migrations/|models/|database/)" > /dev/null; then - LOADED_RULES="$LOADED_RULES .ai/rules/development/database.md" -fi - -# Testing context -if echo "$FILE_PATH" | grep -E "(tests?/|spec/|\.test\.|\.spec\.)" > /dev/null; then - LOADED_RULES="$LOADED_RULES .ai/rules/development/testing.md" -fi - -# Output loaded context as AI message -if [ -n "$LOADED_RULES" ]; then - echo "📋 Auto-loading specialized rules for this context:" - for rule in $LOADED_RULES; do - echo " - $rule" - done - echo "" - echo "AI: Please read these files before proceeding: $LOADED_RULES" -fi - -exit 0 # Allow operation to continue -``` - -**Hook configuration (example for Claude Code, adapt for your AI assistant)**: -```json -{ - "hooks": { - "PreToolUse": [{ - "matcher": "Edit|Write", - "hooks": [{"type": "command", "command": ".ai/hooks/auto-load-context.sh"}] - }] - } -} -``` - -#### Integration with Custom Commands - -Create commands that automatically load relevant context: - -```markdown ---- -description: Implement API endpoint with auto-loaded API design rules -argument-hint: endpoint_name (e.g., "GET /users/:id") ---- - -# API Implementation with Progressive Disclosure - -Before implementing the API endpoint, I will: - -1. **Auto-load specialized context**: - - Read `.ai/rules/development/api-design.md` for API standards - - Read `.ai/rules/security/authentication.md` if endpoint requires auth - - Read `.ai/rules/development/testing.md` for test requirements - -2. **Implement endpoint** following loaded rules: - - RESTful design patterns from api-design.md - - Error handling standards - - Input validation requirements - - Response format consistency - -3. **Generate tests** following testing.md: - - Happy path tests - - Error case coverage - - Authentication/authorization tests - - Input validation tests - -4. **Verify compliance**: - - Check against API design rules - - Run security validation - - Ensure test coverage >80% - -Implement: $ARGUMENTS -``` - -#### Validation & Metrics - -**Measure effectiveness**: - -```bash -# Count instructions in main file (target: <60 lines of actual rules) -grep -v "^#" .ai/CLAUDE.md | grep -v "^$" | wc -l - -# Count specialized rule files (aim for 5-10 domain areas) -find .ai/rules -name "*.md" | wc -l - -# Track context loading patterns (add to event hooks) -echo "$(date): Loaded $LOADED_RULES for $FILE_PATH" >> .ai/context-usage.log - -# Analyze which rules are most frequently loaded -cat .ai/context-usage.log | grep -oE "rules/[^/]+/[^ ]+" | sort | uniq -c | sort -rn -``` - -**Success criteria**: -- Main CLAUDE.md: <60 lines of actual instructions (excluding comments/blank lines) -- Specialized rules: 5-10 focused files, each <100 lines -- Context loading: Automatic via hooks or explicit in commands -- Instruction count per session: <150 total (main + loaded specializations) - -#### Anti-pattern: Bloated Configuration - -**Problem**: Putting all rules in a single configuration file regardless of relevance. - -```markdown -# AI Configuration File - WRONG APPROACH (500+ lines) -# (applies to CLAUDE.md, AGENTS.md, .cursorrules, etc.) - -## Security Rules (100 lines) -- Secret management for .env files -- Dependency scanning procedures -- Authentication implementation standards -- OAuth flow requirements -- API key rotation policies -... - -## Database Rules (80 lines) -- Migration file naming -- Model relationship patterns -- Query optimization guidelines -- Index creation standards -... - -## API Design Rules (90 lines) -- RESTful endpoint patterns -- Response format requirements -- Error handling standards -... - -## Frontend Rules (110 lines) -- Component structure -- State management patterns -- CSS conventions -... - -## Deployment Rules (70 lines) -- Docker build optimization -- Kubernetes manifests -- Blue-green deployment -... - -## Testing Rules (50 lines) -... -``` - -**Why it fails**: -- AI task: "Fix typo in README.md" -- Loaded context: ALL 500 lines of rules (security, database, API, frontend, deployment, testing) -- Relevant context: Maybe 10 lines about code quality and git commit messages -- Result: 490 lines of wasted context, reduced instruction-following accuracy -- Performance: Slower responses, more hallucinations, missed critical instructions - -**Consequences**: -1. **Instruction decay**: With 500+ instructions loaded, AI follows maybe 60-70% accurately -2. **Context waste**: 90% of loaded rules are irrelevant to the task -3. **Maintenance burden**: Editing security rules requires opening 500-line file -4. **Slow responses**: AI processes unnecessary context before every response -5. **Higher costs**: More tokens consumed per interaction -6. **Cognitive overload**: New team members overwhelmed by monolithic config - -**Correct approach**: Progressive Disclosure -- Main file: 40 lines of universal rules + routing instructions -- Specialized files: 8 files × 60 lines = 480 lines total -- Per-task context: 40 (main) + 60 (relevant specialization) = 100 instructions -- Result: 3x better instruction-following, faster responses, easier maintenance - -#### Anti-pattern: Over-Fragmentation - -**Problem**: Creating too many tiny rule files that require constant loading. - -``` -.ai/rules/ -├── api/ -│ ├── get-endpoints.md # 10 lines -│ ├── post-endpoints.md # 12 lines -│ ├── put-endpoints.md # 11 lines -│ ├── delete-endpoints.md # 9 lines -│ ├── error-handling.md # 8 lines -│ ├── validation.md # 15 lines -│ ├── response-format.md # 10 lines -│ └── versioning.md # 7 lines -... -``` - -**Why it fails**: -- API implementation task requires loading 8 different files -- Overhead of reading 8 files > benefit of separation -- Harder to maintain consistency across related rules -- AI must constantly re-read interconnected files - -**Correct approach**: Balance granularity -- Combine related rules: api-design.md (all API rules, ~80 lines) -- Split by clear domains: security/, development/, operations/ -- Aim for 5-10 specialized files, not 50 - -#### Anti-pattern: Missing Guidance - -**Problem**: Creating specialized rule files but not telling the AI when to load them. - -```markdown -# Main Configuration File (no routing) -# (CLAUDE.md, AGENTS.md, .cursorrules, etc.) -Follow the project coding standards. - -# (Specialized rules exist in .ai/rules/ but AI never knows to load them) -``` - -**Why it fails**: -- AI doesn't know specialized rules exist -- Relies on human to remember: "also read .ai/rules/security/secrets.md" -- No automation or consistency - -**Correct approach**: Explicit routing in main file -- Document WHEN to load each specialized file -- Provide file path patterns that trigger loading -- Use event hooks for automatic loading -- Include loading instructions in custom commands - ---- - ### Asynchronous Research **Maturity**: Intermediate @@ -1471,92 +702,6 @@ Simon's caveat: *"They can't prove something is impossible—just because the co ## Operations Automation -### Centralized Rules - -**Maturity**: Advanced -**Description**: Enforce organization-wide AI rules through a central Git repository that syncs to standard AI assistant configuration files (CLAUDE.md, AGENTS.md, .cursorrules) with automatic language and framework detection. - -**Related Patterns**: [Codified Rules](../README.md#codified-rules), [Progressive Disclosure](#progressive-disclosure), [Security Orchestration](../README.md#security-orchestration) - -#### Core Implementation - -**Sync-based Architecture** (Recommended): - -``` -Central Rules Repository (Git) - ├── base/universal-rules.md - ├── languages/ (python.md, typescript.md, go.md) - └── frameworks/ (react.md, django.md, fastapi.md) - ↓ - [sync-ai-rules.sh] - ↓ - Project Repository - ├── CLAUDE.md (auto-generated) - ├── AGENTS.md (auto-generated) - └── .cursorrules (auto-generated) -``` - -**How it works**: - -1. **Central repository** stores organization rules organized by language/framework -2. **Sync script** detects project language (Python, TypeScript, Go) and framework (React, Django, FastAPI) -3. **Auto-generates** standard config files (CLAUDE.md, .cursorrules, etc.) with relevant rules -4. **Works offline** - no API calls, no internet dependencies after initial sync - -**Example sync**: -```bash -# One-time setup per project -curl -O https://yourorg.com/sync-ai-rules.sh -chmod +x sync-ai-rules.sh - -# Run sync (manual or via pre-commit hook) -./sync-ai-rules.sh - -# Generates CLAUDE.md with: -# - Universal org rules -# - Python-specific rules (auto-detected from pyproject.toml) -# - FastAPI rules (auto-detected from dependencies) -``` - -**Key benefits**: -- ✅ **Works with existing AI tools** - Claude Code, Cursor, Gemini all read standard config files -- ✅ **Offline-friendly** - No API gateway, no internet dependencies -- ✅ **Simple** - Single bash script, no Node.js services to deploy -- ✅ **Language-aware** - Auto-detects Python/TypeScript/Go and pulls relevant rules -- ✅ **Version-controlled** - Rules in Git, changes are auditable - -**Alternative: Gateway Pattern** (for advanced use cases): - -For organizations needing input/output filtering, policy enforcement, or usage logging, see [examples/centralized-rules/gateway-strategy/](examples/centralized-rules/gateway-strategy/) for API gateway approach with: -- Request/response filtering -- Policy-as-code integration (OPA/Cedar) -- Centralized audit logging -- Usage metrics aggregation - -Complete Examples: -- **[Sync Strategy](examples/centralized-rules/sync-strategy/)** - Simple Git-based sync (recommended) -- **[Gateway Strategy](examples/centralized-rules/gateway-strategy/)** - Advanced API gateway pattern - -#### Anti-pattern: Scattered Configuration - -Copying AI rule files into every repository without central source: - -``` -repo-a/.cursorrules # v1.2 of org rules -repo-b/CLAUDE.md # v1.1 (outdated) -repo-c/.ai/rules/ # Custom fork, diverged -``` - -**Problems**: -- Rules drift across repositories -- Manual updates required for every repo -- No consistency enforcement -- Difficult to track which repos have current rules - -**Solution**: Use centralized sync approach where rules are maintained in one place and automatically distributed to projects. - ---- - ### Review Automation **Maturity**: Intermediate diff --git a/experiments/examples/README.md b/experiments/examples/README.md index 19db0de..4293ce7 100644 --- a/experiments/examples/README.md +++ b/experiments/examples/README.md @@ -7,12 +7,9 @@ This directory contains working implementations of selected experimental pattern | Experimental Pattern | Example Directory | Notes | |----------------------|------------------|-------| | [Asynchronous Research](../README.md#asynchronous-research) | [`asynchronous-research/`](asynchronous-research/) | Fire-and-forget research workflows | -| [Centralized Rules](../README.md#centralized-rules) | [`centralized-rules/`](centralized-rules/) | Gateway-style enforcement and distribution | -| [Custom Commands](../README.md#custom-commands) | [`custom-commands/`](custom-commands/) | Extend assistants with project-specific commands | | [Debt Forecasting](../README.md#debt-forecasting) | [`debt-forecasting/`](debt-forecasting/) | Proactive technical debt analysis | | [Deployment Synthesis](../README.md#deployment-synthesis) | [`deployment-synthesis/`](deployment-synthesis/) | Generate validated deployment configurations | | [Drift Remediation](../README.md#drift-remediation) | [`drift-remediation/`](drift-remediation/) | Detect and correct infrastructure drift | -| [Event Automation](../README.md#event-automation) | [`event-automation/`](event-automation/) | Automate actions at assistant lifecycle events | | [Handoff Protocols](../README.md#handoff-protocols) | [`handoff-protocols/`](handoff-protocols/) | Human ↔ AI handoff decisioning and procedures | | [Incident Automation](../README.md#incident-automation) | [`incident-automation/`](incident-automation/) | Generate incident response playbooks | | [Pipeline Synthesis](../README.md#pipeline-synthesis) | [`pipeline-synthesis/`](pipeline-synthesis/) | Convert build specs into pipeline configs | diff --git a/index.html b/index.html index 916c1fe..1d92aa0 100644 --- a/index.html +++ b/index.html @@ -41,60 +41,80 @@

AI Development Patterns

License: MIT - Patterns + Patterns

A comprehensive collection of patterns for building software with AI assistance, organized by implementation maturity and development lifecycle phases.

-
-graph TB - RA([Readiness
Assessment]) --> CR([Codified
Rules]) - CR --> SS([Security
Sandbox]) - SS --> DL([Developer
Lifecycle]) - DL --> TI([Tool
Integration]) - - TI --> BM([Baseline
Management]) - SS --> SO([Security
Orchestration]) - SS --> PG([Policy
Generation]) - - DL --> OD([Observable
Development]) - DL --> SD([Spec-Driven
Development]) - DL --> AT([Automated
Traceability]) - CR --> GR([Guided
Refactoring]) - CR --> CP([Context
Persistence]) - RA --> IG([Issue
Generation]) - - PE([Progressive
Enhancement]) --> AD([Atomic
Decomposition]) - AD --> PA([Parallel
Agents]) - - classDef foundation fill:#a8d5ba,stroke:#2d5a3f,stroke-width:2px,color:#1a3a25 - classDef development fill:#f9e79f,stroke:#b7950b,stroke-width:2px,color:#7d6608 - classDef operations fill:#f5b7b1,stroke:#c0392b,stroke-width:2px,color:#78281f - - class RA,CR,SS,DL,TI,IG foundation - class PE,SD,AD,PA,OD,GR,AT development - class CP development - class PG,SO,BM operations - - click RA "https://github.com/PaulDuvall/ai-development-patterns#readiness-assessment" - click CR "https://github.com/PaulDuvall/ai-development-patterns#codified-rules" - click SS "https://github.com/PaulDuvall/ai-development-patterns#security-sandbox" - click DL "https://github.com/PaulDuvall/ai-development-patterns#developer-lifecycle" - click TI "https://github.com/PaulDuvall/ai-development-patterns#tool-integration" - click IG "https://github.com/PaulDuvall/ai-development-patterns#issue-generation" - click CP "https://github.com/PaulDuvall/ai-development-patterns#context-persistence" - click PE "https://github.com/PaulDuvall/ai-development-patterns#progressive-enhancement" - click SD "https://github.com/PaulDuvall/ai-development-patterns#spec-driven-development" - click AD "https://github.com/PaulDuvall/ai-development-patterns#atomic-decomposition" - click PA "https://github.com/PaulDuvall/ai-development-patterns#parallel-agents" - click OD "https://github.com/PaulDuvall/ai-development-patterns#observable-development" - click GR "https://github.com/PaulDuvall/ai-development-patterns#guided-refactoring" - click AT "https://github.com/PaulDuvall/ai-development-patterns#automated-traceability" - click PG "https://github.com/PaulDuvall/ai-development-patterns#policy-generation" - click SO "https://github.com/PaulDuvall/ai-development-patterns#security-orchestration" - click BM "https://github.com/PaulDuvall/ai-development-patterns#baseline-management" -
+
+ graph TB + %% ROW 1: Foundation start (left to right) + RA([Readiness
Assessment]) --> CR([Codified
Rules]) + CR --> SS([Security
Sandbox]) + SS --> DL([Developer
Lifecycle]) + DL --> TI([Tool
Integration]) + + %% ROW 2: Operations & branches (loops back) + TI --> BM([Baseline
Management]) + SS --> SO([Security
Orchestration]) + SS --> PG([Policy
Generation]) + SO --> CZR([Centralized
Rules]) + + %% ROW 3: Development patterns (flows forward again) + DL --> OD([Observable
Development]) + DL --> SD([Spec-Driven
Development]) + DL --> AT([Automated
Traceability]) + CR --> GR([Guided
Refactoring]) + CR --> CP([Context
Persistence]) + RA --> IG([Issue
Generation]) + CR --> EA([Event
Automation]) + SS --> EA + EA --> CC([Custom
Commands]) + SD --> CC + CP --> PD([Progressive
Disclosure]) + CR --> PD + SD --> IS([Image
Spec]) + PD --> CZR + + %% ROW 4: Development chain + PE([Progressive
Enhancement]) --> AD([Atomic
Decomposition]) + AD --> PA([Parallel
Agents]) + PE --> IS + + %% STYLING + classDef foundation fill:#a8d5ba,stroke:#2d5a3f,stroke-width:2px,color:#1a3a25 + classDef development fill:#f9e79f,stroke:#b7950b,stroke-width:2px,color:#7d6608 + classDef operations fill:#f5b7b1,stroke:#c0392b,stroke-width:2px,color:#78281f + + class RA,CR,SS,DL,TI,IG,CP foundation + class PE,SD,AD,PA,OD,GR,AT,EA,CC,PD,IS development + class PG,SO,BM,CZR operations + + %% CLICKABLE LINKS + click RA "https://github.com/PaulDuvall/ai-development-patterns#readiness-assessment" + click CR "https://github.com/PaulDuvall/ai-development-patterns#codified-rules" + click SS "https://github.com/PaulDuvall/ai-development-patterns#security-sandbox" + click DL "https://github.com/PaulDuvall/ai-development-patterns#developer-lifecycle" + click TI "https://github.com/PaulDuvall/ai-development-patterns#tool-integration" + click IG "https://github.com/PaulDuvall/ai-development-patterns#issue-generation" + click CP "https://github.com/PaulDuvall/ai-development-patterns#context-persistence" + click PE "https://github.com/PaulDuvall/ai-development-patterns#progressive-enhancement" + click SD "https://github.com/PaulDuvall/ai-development-patterns#spec-driven-development" + click AD "https://github.com/PaulDuvall/ai-development-patterns#atomic-decomposition" + click PA "https://github.com/PaulDuvall/ai-development-patterns#parallel-agents" + click OD "https://github.com/PaulDuvall/ai-development-patterns#observable-development" + click GR "https://github.com/PaulDuvall/ai-development-patterns#guided-refactoring" + click AT "https://github.com/PaulDuvall/ai-development-patterns#automated-traceability" + click EA "https://github.com/PaulDuvall/ai-development-patterns#event-automation" + click CC "https://github.com/PaulDuvall/ai-development-patterns#custom-commands" + click PD "https://github.com/PaulDuvall/ai-development-patterns#progressive-disclosure" + click IS "https://github.com/PaulDuvall/ai-development-patterns#image-spec" + click PG "https://github.com/PaulDuvall/ai-development-patterns#policy-generation" + click SO "https://github.com/PaulDuvall/ai-development-patterns#security-orchestration" + click CZR "https://github.com/PaulDuvall/ai-development-patterns#centralized-rules" + click BM "https://github.com/PaulDuvall/ai-development-patterns#baseline-management" +

Legend: 🟢 Foundation | 🟡 Development | 🔴 Operations

diff --git a/tests/conftest.py b/tests/conftest.py index 1f021c7..1754a00 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -54,12 +54,12 @@ def experiments_dir(): "Foundation": ["Readiness Assessment", "Codified Rules", "Security Sandbox", "Developer Lifecycle", "Tool Integration", "Issue Generation"], "Development": ["Spec-Driven Development", "Planned Implementation", "Progressive Enhancement", - "Choice Generation", "Parallel Agents", "Context Persistence", - "Constrained Generation", "Atomic Decomposition", + "Image Spec", "Choice Generation", "Parallel Agents", "Context Persistence", + "Constrained Generation", "Event Automation", "Custom Commands", "Progressive Disclosure", "Atomic Decomposition", "Observable Development", "Guided Refactoring", "Guided Architecture", "Automated Traceability", "Error Resolution"], "Operations": ["Policy Generation", "Security Orchestration", - "Baseline Management"] + "Centralized Rules", "Baseline Management"] } # Expected patterns from the reference table @@ -71,6 +71,7 @@ def experiments_dir(): "Tool Integration", "Issue Generation", "Spec-Driven Development", + "Image Spec", "Planned Implementation", "Progressive Enhancement", "Choice Generation", @@ -78,6 +79,9 @@ def experiments_dir(): "Parallel Agents", "Context Persistence", "Constrained Generation", + "Event Automation", + "Custom Commands", + "Progressive Disclosure", "Observable Development", "Guided Refactoring", "Guided Architecture", @@ -85,5 +89,6 @@ def experiments_dir(): "Error Resolution", "Policy Generation", "Security Orchestration", + "Centralized Rules", "Baseline Management" -] \ No newline at end of file +]