From 16e8b955dfba64b787e2177bd178419cf88e26d9 Mon Sep 17 00:00:00 2001 From: d33bs Date: Thu, 21 May 2026 11:19:09 -0600 Subject: [PATCH 1/2] add agent skills --- .agents/skills/ci-cd-and-automation/SKILL.md | 33 +++++ .../skills/code-review-and-quality/SKILL.md | 36 +++++ .../debugging-and-error-recovery/SKILL.md | 39 +++++ .../incremental-implementation/SKILL.md | 36 +++++ .../skills/learning-opportunities/SKILL.md | 134 ++++++++++++++++++ .../skills/test-driven-development/SKILL.md | 44 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 2 +- .markdownlint.json | 6 + .markdownlint.json.jinja | 6 + .pre-commit-config.yaml | 4 + .pre-commit-config.yaml.jinja | 4 + AGENTS.md | 42 ++++++ CITATION.cff | 15 ++ CITATION.cff.jinja | 15 ++ CONTRIBUTING.md | 4 +- README.md | 27 +++- README.md.jinja | 25 ++++ pyproject.toml.jinja | 7 + 18 files changed, 475 insertions(+), 4 deletions(-) create mode 100644 .agents/skills/ci-cd-and-automation/SKILL.md create mode 100644 .agents/skills/code-review-and-quality/SKILL.md create mode 100644 .agents/skills/debugging-and-error-recovery/SKILL.md create mode 100644 .agents/skills/incremental-implementation/SKILL.md create mode 100644 .agents/skills/learning-opportunities/SKILL.md create mode 100644 .agents/skills/test-driven-development/SKILL.md create mode 100644 .markdownlint.json create mode 100644 .markdownlint.json.jinja create mode 100644 AGENTS.md diff --git a/.agents/skills/ci-cd-and-automation/SKILL.md b/.agents/skills/ci-cd-and-automation/SKILL.md new file mode 100644 index 0000000..b42d312 --- /dev/null +++ b/.agents/skills/ci-cd-and-automation/SKILL.md @@ -0,0 +1,33 @@ +--- +name: ci-cd-and-automation +description: Keeps delivery workflows automated and repeatable. Use when adding checks, changing pipelines, or improving contributor onboarding. +--- + +# CI/CD and Automation + +## Overview + +Prefer one-command local pipelines and CI parity so contributors can validate changes quickly and consistently. + +## Rules + +- If a check is required in CI, provide an easy local path to run it. +- Keep commands discoverable in Poe tasks instead of ad-hoc docs only. +- Prefer stable defaults and explicit failure signals. + +## Project convention + +- Maintain a complete local pipeline task: `uv run --frozen poe pipeline` +- Keep focused tasks for: + - `uv run --frozen poe test` + - `uv run --frozen poe lint` + +## Change checklist + +1. Update `pyproject.toml` Poe tasks when checks change. +2. Keep GitHub Actions and local tasks aligned. +3. Verify full local pipeline before completion. + +## Verification + +- `uv run --frozen poe pipeline` diff --git a/.agents/skills/code-review-and-quality/SKILL.md b/.agents/skills/code-review-and-quality/SKILL.md new file mode 100644 index 0000000..bb563d6 --- /dev/null +++ b/.agents/skills/code-review-and-quality/SKILL.md @@ -0,0 +1,36 @@ +--- +name: code-review-and-quality +description: Runs a multi-axis quality review before merge. Use after implementation and before considering work complete. +--- + +# Code Review and Quality + +## Overview + +Every non-trivial change should be reviewed across correctness, readability, architecture, security, and performance. + +## Five-axis review + +1. Correctness: does behavior match requirements and edge cases? +2. Readability: is intent clear and maintainable? +3. Architecture: are boundaries and abstractions appropriate? +4. Security: are inputs validated and risky paths handled safely? +5. Performance: any obvious regressions or expensive paths? + +## Rules + +- Fix critical issues before completion. +- Keep feedback actionable and specific. +- Prefer smaller, reviewable changes over large diffs. +- Approve when the change clearly improves code health, even if not perfect. + +## Quality gates + +- Tests pass for changed behavior. +- Lint/type checks pass. +- No known high-severity defects remain. + +## Suggested commands + +- `uv run --frozen pytest` +- `pre-commit run --all-files` diff --git a/.agents/skills/debugging-and-error-recovery/SKILL.md b/.agents/skills/debugging-and-error-recovery/SKILL.md new file mode 100644 index 0000000..6e8989d --- /dev/null +++ b/.agents/skills/debugging-and-error-recovery/SKILL.md @@ -0,0 +1,39 @@ +--- +name: debugging-and-error-recovery +description: Systematic debugging workflow for failing tests, CI breakages, and runtime errors. Use when behavior is unexpected or a check fails. +--- + +# Debugging and Error Recovery + +## Overview + +Use a disciplined triage loop: reproduce, localize, reduce, fix, and guard against regressions. + +## When to use + +- CI failures +- Test regressions +- Runtime exceptions +- Template rendering or environment issues + +## Workflow + +1. Reproduce the issue with the smallest reliable command. +2. Localize failure to a file, function, or boundary. +3. Reduce to the minimal failing case. +4. Implement the smallest safe fix. +5. Add or update tests to prevent recurrence. +6. Re-run relevant checks, then broader validation. + +## Rules + +- Do not patch blindly without reproducing. +- Prefer evidence from logs, traces, and failing assertions. +- Keep recovery changes scoped; avoid unrelated refactors. +- If root cause is uncertain, state assumptions and verify them. + +## Suggested commands + +- Targeted tests: `uv run --frozen pytest tests/ -q` +- Full tests: `uv run --frozen pytest` +- Full quality gate: `uv run --frozen poe pipeline` diff --git a/.agents/skills/incremental-implementation/SKILL.md b/.agents/skills/incremental-implementation/SKILL.md new file mode 100644 index 0000000..a0d9c82 --- /dev/null +++ b/.agents/skills/incremental-implementation/SKILL.md @@ -0,0 +1,36 @@ +--- +name: incremental-implementation +description: Delivers changes in thin, verifiable slices. Use when a task spans multiple files or feels too large for one safe change. +--- + +# Incremental Implementation + +## Overview + +Build in small vertical slices: implement, test, verify, then continue. Each increment should keep the project in a working state. + +## When to use + +- Multi-file features +- Refactors with risk +- Any task where scope is likely to expand + +## Increment cycle + +1. Implement the smallest complete slice. +2. Run relevant tests and checks. +3. Verify behavior manually if needed. +4. Commit or checkpoint. +5. Move to the next slice. + +## Rules + +- Scope discipline: do only what the current slice requires. +- Keep each increment reversible. +- Avoid broad cleanups mixed with feature work. +- Use safe defaults and feature flags when partial work must merge. + +## Verification + +- `uv run --frozen pytest` +- `pre-commit run --all-files` diff --git a/.agents/skills/learning-opportunities/SKILL.md b/.agents/skills/learning-opportunities/SKILL.md new file mode 100644 index 0000000..af3bbb1 --- /dev/null +++ b/.agents/skills/learning-opportunities/SKILL.md @@ -0,0 +1,134 @@ +--- +name: learning-opportunities +description: Facilitates deliberate skill development during AI-assisted coding. Offers interactive learning exercises after architectural work (new files, schema changes, refactors). Use when completing features, making design decisions, or when user asks to understand code better. +argument-hint: "[orient]" +license: CC-BY-4.0 +source: "Adapted from DrCatHicks/learning-opportunities" +source_url: "https://github.com/DrCatHicks/learning-opportunities/tree/main/learning-opportunities" +--- + +# Learning Opportunities + +> Invocation argument: `$ARGUMENTS` + +## Purpose + +The user wants to build genuine expertise while using AI coding tools, not just ship code. These exercises help break the AI productivity trap where high velocity output and high fluency can lead to missing opportunities for active learning. + +## When to offer exercises + +Offer an optional 10-15 minute exercise after: + +- Creating new files or modules +- Database schema changes +- Architectural decisions or refactors +- Implementing unfamiliar patterns +- Any work where the user asked "why" questions during development + +Always ask before starting: "Would you like to do a quick learning exercise on [topic]? About 10-15 minutes." + +## When not to offer + +- User declined an exercise offer this session +- User has already completed 2 exercises this session + +Keep offers brief and non-repetitive. + +## Core principle: Pause for input + +End your message immediately after the question. Do not generate any further content after the pause point. + +After the pause point, do not generate: + +- Suggested or example responses +- Hints disguised as encouragement +- Multiple questions in sequence +- Any teaching content + +Allowed after the question: + +- Content-free reassurance: "(Take your best guess—wrong predictions are useful data.)" +- Escape hatch: "(Or we can skip this one.)" + +Pause pattern: + +1. Pose a specific question or task. +2. Wait for the user's response. +3. Provide feedback connected to actual behavior. +4. If prediction was wrong, clearly identify what was incorrect and explore the gap. +5. Do not attribute insights the user did not express. + +## Exercise types + +### Prediction -> Observation -> Reflection + +1. Pause with a concrete prediction question. +2. Wait. +3. Walk through actual behavior. +4. Pause for reflection on surprise and match. + +### Generation -> Comparison + +1. Ask user to sketch approach before showing implementation. +2. Wait. +3. Show actual implementation. +4. Compare and discuss rationale. + +### Trace the path + +1. Use concrete values. +2. Pause at each decision point. +3. Wait before revealing each step. +4. Continue through full path. + +### Debug this + +1. Present plausible bug or edge case. +2. Pause: what breaks and why. +3. Wait. +4. Pause: how to fix. +5. Discuss approach. + +### Teach it back + +1. Ask user to explain a component as if onboarding a new developer. +2. Wait. +3. Provide targeted feedback. + +### Retrieval check-in + +At start of returning sessions: + +1. Ask what they remember about a prior component/scenario. +2. Wait. +3. Fill gaps or confirm. + +## Facilitation guidelines + +- Ask if they want to engage before starting. +- Honor response time and silence. +- Adjust difficulty dynamically. +- Keep exercises effortful but not frustrating. +- Keep exercises to 10-15 minutes unless user wants deeper work. +- Be direct about errors and non-judgmental in explanation. + +## Hands-on exploration defaults + +- Prefer directing users to files over pasting large code snippets. +- Use completion-style prompts and fading scaffolding. +- If struggling, increase scaffolding specificity rather than hinting answers. + +## Orientation mode (`orient`) + +If invoked with `orient`, run a guided repo orientation exercise instead of the default offer flow. + +Look for `resources/orientation.md` in this order: + +1. `.agents/skills/learning-opportunities/resources/orientation.md` +2. `~/.agents/skills/learning-opportunities/resources/orientation.md` +3. `.codex/skills/learning-opportunities/resources/orientation.md` +4. `~/.codex/skills/learning-opportunities/resources/orientation.md` +5. `.claude/skills/learning-opportunities/resources/orientation.md` +6. `~/.claude/skills/learning-opportunities/resources/orientation.md` + +If no orientation file is found, stop and ask the user to generate one first. diff --git a/.agents/skills/test-driven-development/SKILL.md b/.agents/skills/test-driven-development/SKILL.md new file mode 100644 index 0000000..0babc2f --- /dev/null +++ b/.agents/skills/test-driven-development/SKILL.md @@ -0,0 +1,44 @@ +--- +name: test-driven-development +description: Drives development with tests first. Use when implementing logic, fixing bugs, or changing behavior that must be proven. +--- + +# Test-Driven Development + +## Overview + +Write a failing test before writing code that makes it pass. For bug fixes, reproduce the bug with a test first. Tests are proof. + +## When to use + +- Implementing new behavior +- Fixing bugs (prove-it pattern) +- Refactoring behavior with regression risk + +## Red-Green-Refactor + +1. Define expected behavior first. +2. Write a failing test (RED). +3. Implement the smallest change to pass (GREEN). +4. Clean up without changing behavior (REFACTOR). +5. Re-run tests after each meaningful change. + +## Prove-it pattern for bugs + +1. Reproduce the bug with a test. +2. Confirm the test fails. +3. Implement the fix. +4. Confirm the test passes. +5. Run broader tests to check for regressions. + +## Rules + +- Prefer state/output assertions over implementation-detail assertions. +- Keep tests descriptive and behavior-focused. +- Avoid skipping tests to make the suite pass. +- Do not run the same command repeatedly without code changes in between. + +## Suggested commands + +- Targeted: `uv run --frozen pytest tests/test_main.py -q` +- Full: `uv run --frozen pytest` diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 66a3c90..fdbb700 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -24,7 +24,7 @@ Pre-commit checks will automatically run as part of opening this pull request an - [ ] Enhancement (adds functionality). - [ ] Breaking change (these changes would cause existing functionality to not work as expected). -# Checklist +## Checklist Please ensure that all boxes are checked before indicating that this pull request is ready for review. diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..1dd8622 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,6 @@ +{ + "default": true, + "MD013": false, + "MD033": false, + "MD041": false +} diff --git a/.markdownlint.json.jinja b/.markdownlint.json.jinja new file mode 100644 index 0000000..1dd8622 --- /dev/null +++ b/.markdownlint.json.jinja @@ -0,0 +1,6 @@ +{ + "default": true, + "MD013": false, + "MD033": false, + "MD041": false +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f25201d..643a0b7 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -33,6 +33,10 @@ repos: - id: mdformat additional_dependencies: - mdformat-gfm +- repo: https://github.com/DavidAnson/markdownlint-cli2 + rev: v0.18.1 + hooks: + - id: markdownlint-cli2 - repo: https://github.com/adrienverge/yamllint rev: v1.38.0 hooks: diff --git a/.pre-commit-config.yaml.jinja b/.pre-commit-config.yaml.jinja index 1fc8980..25644d1 100644 --- a/.pre-commit-config.yaml.jinja +++ b/.pre-commit-config.yaml.jinja @@ -33,6 +33,10 @@ repos: - id: mdformat additional_dependencies: - mdformat-gfm +- repo: https://github.com/DavidAnson/markdownlint-cli2 + rev: v0.18.1 + hooks: + - id: markdownlint-cli2 - repo: https://github.com/adrienverge/yamllint rev: v1.37.1 hooks: diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..816b570 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# Agent Guide + +This repository includes local agent guidance in `.agents/skills/`. + +## Where agent guidance lives + +- Root guide: `AGENTS.md` +- Skills directory: `.agents/skills/` +- Skill directories: + - `.agents/skills/test-driven-development/SKILL.md` + - `.agents/skills/incremental-implementation/SKILL.md` + - `.agents/skills/code-review-and-quality/SKILL.md` + - `.agents/skills/ci-cd-and-automation/SKILL.md` + - `.agents/skills/debugging-and-error-recovery/SKILL.md` + - `.agents/skills/learning-opportunities/SKILL.md` + +## How to use these skills + +- Load relevant skill(s) before making edits. +- Prefer small changes with frequent validation. +- Keep work aligned with this project's `pyproject.toml`, CI workflows, and pre-commit hooks. + +## Default execution order + +1. Apply `test-driven-development` when behavior changes. +2. Apply `incremental-implementation` for multi-file or higher-risk changes. +3. Apply `code-review-and-quality` as the final quality gate before completion. +4. Apply `ci-cd-and-automation` when changing checks, tasks, or pipelines. +5. Apply `debugging-and-error-recovery` when tests, CI, or runtime behavior fails unexpectedly. +6. Optionally apply `learning-opportunities` for 10-15 minute learning exercises after design-heavy work. + +## Local commands + +- Run tests: `uv run --frozen pytest` +- Run lint/format hooks: `pre-commit run --all-files` +- Run type checks via pre-commit hook: `pre-commit run ty --all-files` +- Run full local pipeline: `uv run --frozen poe pipeline` + +## Scope expectations + +- These instructions are project-local. +- If team standards evolve, update these files in-place. diff --git a/CITATION.cff b/CITATION.cff index 93fac9c..6792637 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -23,3 +23,18 @@ license: BSD-3-Clause identifiers: - type: doi value: "10.5281/zenodo.15518401" +references: + - type: software + title: "agent-skills" + authors: + - given-names: Addy + family-names: Osmani + repository-code: "https://github.com/addyosmani/agent-skills" + license: MIT + - type: software + title: "learning-opportunities" + authors: + - given-names: Dan + family-names: Hicks + repository-code: "https://github.com/DrCatHicks/learning-opportunities" + license: CC-BY-4.0 diff --git a/CITATION.cff.jinja b/CITATION.cff.jinja index 05d889c..372dc1d 100644 --- a/CITATION.cff.jinja +++ b/CITATION.cff.jinja @@ -20,3 +20,18 @@ abstract: >- keywords: - python license: BSD-3-Clause +references: + - type: software + title: "agent-skills" + authors: + - given-names: Addy + family-names: Osmani + repository-code: "https://github.com/addyosmani/agent-skills" + license: MIT + - type: software + title: "learning-opportunities" + authors: + - given-names: Dan + family-names: Hicks + repository-code: "https://github.com/DrCatHicks/learning-opportunities" + license: CC-BY-4.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 68aa978..5f13380 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,7 +57,7 @@ We welcome anyone to use [GitHub issues](https://docs.github.com/en/issues/track Specifically, there are several ways to suggest or make changes to this repository: -1. Open a GitHub issue: https://github.com/CU-DBMI/template-uv-python-research-software/issues +1. Open a [GitHub issue](https://github.com/CU-DBMI/template-uv-python-research-software/issues) 1. Create a pull request from a forked branch of the repository ### Creating a pull request @@ -93,7 +93,7 @@ Versioning for the project is intended to align with GitHub Releases which provi ### Releases -We publish source code by using [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) available [here](https://github.com/CU-DBMI/template-uv-python-research-software/releases). +We publish source code by using [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) available in the [template-uv-python-research-software releases page](https://github.com/CU-DBMI/template-uv-python-research-software/releases). #### Release Publishing Process diff --git a/README.md b/README.md index 8b05096..044c307 100644 --- a/README.md +++ b/README.md @@ -7,12 +7,37 @@ This is a [`copier`](https://github.com/copier-org/copier) template for building Python research software through the `uv` environment manager. +## High-level overview + +Projects generated from this template include: + +- `uv`-managed environments and dependencies +- Testing and coverage defaults via `pytest` + `coverage.py` +- Pre-commit automation for formatting, linting, and type checks +- GitHub Actions workflows for linting, tests, docs, and release-related automation +- Starter package + CLI scaffold under `src/` +- Documentation scaffold under `docs/` +- Poe task entrypoints for common local workflows (including a full local pipeline task) + +## Included agent skills + +Generated projects include agent guidance in `.agents/skills/` with common skills for: + +- Test-driven development +- Incremental implementation +- Code review and quality checks +- CI/CD and automation workflow alignment +- Debugging and error recovery +- Optional learning exercises for comprehension (`learning-opportunities`) + +If you do not want to use local agent guidance in your project, remove `AGENTS.md` and the `.agents/` directory. + ## Using this template Follow these steps to use this template: 1. [Install `copier`](https://copier.readthedocs.io/en/stable/#installation) (e.g. `pip install copier`). -1. Reference this repository through the `copier copy ` command. (e.g. `copier copy --vcs-ref=HEAD https://github.com/cu-dbmi/template-uv-python-research-software destination_path`) +1. Reference this repository through the `copier copy ` command. (e.g. `uvx copier copy --vcs-ref=HEAD https://github.com/cu-dbmi/template-uv-python-research-software destination_path`) If you still see stale content, clear Copier's cache (`rm -rf ~/.cache/copier`) and run the command again. 1. Follow the directions in your new repo's `README.md` and make sure to check each file for alignment with your project. 1. Enjoy! diff --git a/README.md.jinja b/README.md.jinja index 6cfd723..2a1ee20 100644 --- a/README.md.jinja +++ b/README.md.jinja @@ -2,6 +2,31 @@ {{ project_description }} +## High-level overview + +This template gives you a ready-to-run Python research software project with: + +- `uv`-managed environments and dependencies +- Testing and coverage defaults via `pytest` + `coverage.py` +- Pre-commit automation for formatting, linting, and type checks +- GitHub Actions workflows for linting, tests, docs, and release-related automation +- Starter package + CLI scaffold under `src/` +- Documentation scaffold under `docs/` +- Poe task entrypoints for common local workflows (including a full local pipeline task) + +## Included agent skills + +This project includes agent guidance in `.agents/skills/` with common skills for: + +- Test-driven development +- Incremental implementation +- Code review and quality checks +- CI/CD and automation workflow alignment +- Debugging and error recovery +- Optional learning exercises (`learning-opportunities`) + +If you do not want to use local agent guidance in your project, remove `AGENTS.md` and the `.agents/` directory. + ## Post template copy instructions While we provide some customizations to the files in this template based on your specification there's likely a chance some things aren't perfect. diff --git a/pyproject.toml.jinja b/pyproject.toml.jinja index a14abeb..cb9d8e7 100644 --- a/pyproject.toml.jinja +++ b/pyproject.toml.jinja @@ -102,6 +102,13 @@ skip_covered = true test.shell = """ pytest """ +lint.shell = """ +pre-commit run --all-files +""" +pipeline.shell = """ +pre-commit run --all-files +pytest +""" jupyter.shell = """ jupyter lab """ From afd875f12ebabc47fa7ee255c1d554f6921a2853 Mon Sep 17 00:00:00 2001 From: d33bs Date: Thu, 21 May 2026 11:29:32 -0600 Subject: [PATCH 2/2] more reasonable md lints --- .agents/skills/ci-cd-and-automation/SKILL.md | 11 ++-- .../skills/code-review-and-quality/SKILL.md | 15 +++-- .../debugging-and-error-recovery/SKILL.md | 17 +++-- .../incremental-implementation/SKILL.md | 15 +++-- .../skills/learning-opportunities/SKILL.md | 63 +++++++++---------- .../skills/test-driven-development/SKILL.md | 23 ++++--- .markdownlint.json | 6 -- .markdownlint.json.jinja | 6 -- .pre-commit-config.yaml | 4 -- .pre-commit-config.yaml.jinja | 4 -- AGENTS.md | 10 +-- 11 files changed, 72 insertions(+), 102 deletions(-) delete mode 100644 .markdownlint.json delete mode 100644 .markdownlint.json.jinja diff --git a/.agents/skills/ci-cd-and-automation/SKILL.md b/.agents/skills/ci-cd-and-automation/SKILL.md index b42d312..a9308fe 100644 --- a/.agents/skills/ci-cd-and-automation/SKILL.md +++ b/.agents/skills/ci-cd-and-automation/SKILL.md @@ -1,7 +1,6 @@ ---- -name: ci-cd-and-automation -description: Keeps delivery workflows automated and repeatable. Use when adding checks, changing pipelines, or improving contributor onboarding. ---- +______________________________________________________________________ + +## name: ci-cd-and-automation description: Keeps delivery workflows automated and repeatable. Use when adding checks, changing pipelines, or improving contributor onboarding. # CI/CD and Automation @@ -25,8 +24,8 @@ Prefer one-command local pipelines and CI parity so contributors can validate ch ## Change checklist 1. Update `pyproject.toml` Poe tasks when checks change. -2. Keep GitHub Actions and local tasks aligned. -3. Verify full local pipeline before completion. +1. Keep GitHub Actions and local tasks aligned. +1. Verify full local pipeline before completion. ## Verification diff --git a/.agents/skills/code-review-and-quality/SKILL.md b/.agents/skills/code-review-and-quality/SKILL.md index bb563d6..51fe96a 100644 --- a/.agents/skills/code-review-and-quality/SKILL.md +++ b/.agents/skills/code-review-and-quality/SKILL.md @@ -1,7 +1,6 @@ ---- -name: code-review-and-quality -description: Runs a multi-axis quality review before merge. Use after implementation and before considering work complete. ---- +______________________________________________________________________ + +## name: code-review-and-quality description: Runs a multi-axis quality review before merge. Use after implementation and before considering work complete. # Code Review and Quality @@ -12,10 +11,10 @@ Every non-trivial change should be reviewed across correctness, readability, arc ## Five-axis review 1. Correctness: does behavior match requirements and edge cases? -2. Readability: is intent clear and maintainable? -3. Architecture: are boundaries and abstractions appropriate? -4. Security: are inputs validated and risky paths handled safely? -5. Performance: any obvious regressions or expensive paths? +1. Readability: is intent clear and maintainable? +1. Architecture: are boundaries and abstractions appropriate? +1. Security: are inputs validated and risky paths handled safely? +1. Performance: any obvious regressions or expensive paths? ## Rules diff --git a/.agents/skills/debugging-and-error-recovery/SKILL.md b/.agents/skills/debugging-and-error-recovery/SKILL.md index 6e8989d..6dcae87 100644 --- a/.agents/skills/debugging-and-error-recovery/SKILL.md +++ b/.agents/skills/debugging-and-error-recovery/SKILL.md @@ -1,7 +1,6 @@ ---- -name: debugging-and-error-recovery -description: Systematic debugging workflow for failing tests, CI breakages, and runtime errors. Use when behavior is unexpected or a check fails. ---- +______________________________________________________________________ + +## name: debugging-and-error-recovery description: Systematic debugging workflow for failing tests, CI breakages, and runtime errors. Use when behavior is unexpected or a check fails. # Debugging and Error Recovery @@ -19,11 +18,11 @@ Use a disciplined triage loop: reproduce, localize, reduce, fix, and guard again ## Workflow 1. Reproduce the issue with the smallest reliable command. -2. Localize failure to a file, function, or boundary. -3. Reduce to the minimal failing case. -4. Implement the smallest safe fix. -5. Add or update tests to prevent recurrence. -6. Re-run relevant checks, then broader validation. +1. Localize failure to a file, function, or boundary. +1. Reduce to the minimal failing case. +1. Implement the smallest safe fix. +1. Add or update tests to prevent recurrence. +1. Re-run relevant checks, then broader validation. ## Rules diff --git a/.agents/skills/incremental-implementation/SKILL.md b/.agents/skills/incremental-implementation/SKILL.md index a0d9c82..afdd771 100644 --- a/.agents/skills/incremental-implementation/SKILL.md +++ b/.agents/skills/incremental-implementation/SKILL.md @@ -1,7 +1,6 @@ ---- -name: incremental-implementation -description: Delivers changes in thin, verifiable slices. Use when a task spans multiple files or feels too large for one safe change. ---- +______________________________________________________________________ + +## name: incremental-implementation description: Delivers changes in thin, verifiable slices. Use when a task spans multiple files or feels too large for one safe change. # Incremental Implementation @@ -18,10 +17,10 @@ Build in small vertical slices: implement, test, verify, then continue. Each inc ## Increment cycle 1. Implement the smallest complete slice. -2. Run relevant tests and checks. -3. Verify behavior manually if needed. -4. Commit or checkpoint. -5. Move to the next slice. +1. Run relevant tests and checks. +1. Verify behavior manually if needed. +1. Commit or checkpoint. +1. Move to the next slice. ## Rules diff --git a/.agents/skills/learning-opportunities/SKILL.md b/.agents/skills/learning-opportunities/SKILL.md index af3bbb1..4ffe551 100644 --- a/.agents/skills/learning-opportunities/SKILL.md +++ b/.agents/skills/learning-opportunities/SKILL.md @@ -1,11 +1,6 @@ ---- -name: learning-opportunities -description: Facilitates deliberate skill development during AI-assisted coding. Offers interactive learning exercises after architectural work (new files, schema changes, refactors). Use when completing features, making design decisions, or when user asks to understand code better. -argument-hint: "[orient]" -license: CC-BY-4.0 -source: "Adapted from DrCatHicks/learning-opportunities" -source_url: "https://github.com/DrCatHicks/learning-opportunities/tree/main/learning-opportunities" ---- +______________________________________________________________________ + +## name: learning-opportunities description: Facilitates deliberate skill development during AI-assisted coding. Offers interactive learning exercises after architectural work (new files, schema changes, refactors). Use when completing features, making design decisions, or when user asks to understand code better. argument-hint: "[orient]" license: CC-BY-4.0 source: "Adapted from DrCatHicks/learning-opportunities" source_url: "https://github.com/DrCatHicks/learning-opportunities/tree/main/learning-opportunities" # Learning Opportunities @@ -53,55 +48,55 @@ Allowed after the question: Pause pattern: 1. Pose a specific question or task. -2. Wait for the user's response. -3. Provide feedback connected to actual behavior. -4. If prediction was wrong, clearly identify what was incorrect and explore the gap. -5. Do not attribute insights the user did not express. +1. Wait for the user's response. +1. Provide feedback connected to actual behavior. +1. If prediction was wrong, clearly identify what was incorrect and explore the gap. +1. Do not attribute insights the user did not express. ## Exercise types ### Prediction -> Observation -> Reflection 1. Pause with a concrete prediction question. -2. Wait. -3. Walk through actual behavior. -4. Pause for reflection on surprise and match. +1. Wait. +1. Walk through actual behavior. +1. Pause for reflection on surprise and match. ### Generation -> Comparison 1. Ask user to sketch approach before showing implementation. -2. Wait. -3. Show actual implementation. -4. Compare and discuss rationale. +1. Wait. +1. Show actual implementation. +1. Compare and discuss rationale. ### Trace the path 1. Use concrete values. -2. Pause at each decision point. -3. Wait before revealing each step. -4. Continue through full path. +1. Pause at each decision point. +1. Wait before revealing each step. +1. Continue through full path. ### Debug this 1. Present plausible bug or edge case. -2. Pause: what breaks and why. -3. Wait. -4. Pause: how to fix. -5. Discuss approach. +1. Pause: what breaks and why. +1. Wait. +1. Pause: how to fix. +1. Discuss approach. ### Teach it back 1. Ask user to explain a component as if onboarding a new developer. -2. Wait. -3. Provide targeted feedback. +1. Wait. +1. Provide targeted feedback. ### Retrieval check-in At start of returning sessions: 1. Ask what they remember about a prior component/scenario. -2. Wait. -3. Fill gaps or confirm. +1. Wait. +1. Fill gaps or confirm. ## Facilitation guidelines @@ -125,10 +120,10 @@ If invoked with `orient`, run a guided repo orientation exercise instead of the Look for `resources/orientation.md` in this order: 1. `.agents/skills/learning-opportunities/resources/orientation.md` -2. `~/.agents/skills/learning-opportunities/resources/orientation.md` -3. `.codex/skills/learning-opportunities/resources/orientation.md` -4. `~/.codex/skills/learning-opportunities/resources/orientation.md` -5. `.claude/skills/learning-opportunities/resources/orientation.md` -6. `~/.claude/skills/learning-opportunities/resources/orientation.md` +1. `~/.agents/skills/learning-opportunities/resources/orientation.md` +1. `.codex/skills/learning-opportunities/resources/orientation.md` +1. `~/.codex/skills/learning-opportunities/resources/orientation.md` +1. `.claude/skills/learning-opportunities/resources/orientation.md` +1. `~/.claude/skills/learning-opportunities/resources/orientation.md` If no orientation file is found, stop and ask the user to generate one first. diff --git a/.agents/skills/test-driven-development/SKILL.md b/.agents/skills/test-driven-development/SKILL.md index 0babc2f..a229f51 100644 --- a/.agents/skills/test-driven-development/SKILL.md +++ b/.agents/skills/test-driven-development/SKILL.md @@ -1,7 +1,6 @@ ---- -name: test-driven-development -description: Drives development with tests first. Use when implementing logic, fixing bugs, or changing behavior that must be proven. ---- +______________________________________________________________________ + +## name: test-driven-development description: Drives development with tests first. Use when implementing logic, fixing bugs, or changing behavior that must be proven. # Test-Driven Development @@ -18,18 +17,18 @@ Write a failing test before writing code that makes it pass. For bug fixes, repr ## Red-Green-Refactor 1. Define expected behavior first. -2. Write a failing test (RED). -3. Implement the smallest change to pass (GREEN). -4. Clean up without changing behavior (REFACTOR). -5. Re-run tests after each meaningful change. +1. Write a failing test (RED). +1. Implement the smallest change to pass (GREEN). +1. Clean up without changing behavior (REFACTOR). +1. Re-run tests after each meaningful change. ## Prove-it pattern for bugs 1. Reproduce the bug with a test. -2. Confirm the test fails. -3. Implement the fix. -4. Confirm the test passes. -5. Run broader tests to check for regressions. +1. Confirm the test fails. +1. Implement the fix. +1. Confirm the test passes. +1. Run broader tests to check for regressions. ## Rules diff --git a/.markdownlint.json b/.markdownlint.json deleted file mode 100644 index 1dd8622..0000000 --- a/.markdownlint.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "default": true, - "MD013": false, - "MD033": false, - "MD041": false -} diff --git a/.markdownlint.json.jinja b/.markdownlint.json.jinja deleted file mode 100644 index 1dd8622..0000000 --- a/.markdownlint.json.jinja +++ /dev/null @@ -1,6 +0,0 @@ -{ - "default": true, - "MD013": false, - "MD033": false, - "MD041": false -} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 643a0b7..f25201d 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -33,10 +33,6 @@ repos: - id: mdformat additional_dependencies: - mdformat-gfm -- repo: https://github.com/DavidAnson/markdownlint-cli2 - rev: v0.18.1 - hooks: - - id: markdownlint-cli2 - repo: https://github.com/adrienverge/yamllint rev: v1.38.0 hooks: diff --git a/.pre-commit-config.yaml.jinja b/.pre-commit-config.yaml.jinja index 25644d1..1fc8980 100644 --- a/.pre-commit-config.yaml.jinja +++ b/.pre-commit-config.yaml.jinja @@ -33,10 +33,6 @@ repos: - id: mdformat additional_dependencies: - mdformat-gfm -- repo: https://github.com/DavidAnson/markdownlint-cli2 - rev: v0.18.1 - hooks: - - id: markdownlint-cli2 - repo: https://github.com/adrienverge/yamllint rev: v1.37.1 hooks: diff --git a/AGENTS.md b/AGENTS.md index 816b570..3539320 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,11 +23,11 @@ This repository includes local agent guidance in `.agents/skills/`. ## Default execution order 1. Apply `test-driven-development` when behavior changes. -2. Apply `incremental-implementation` for multi-file or higher-risk changes. -3. Apply `code-review-and-quality` as the final quality gate before completion. -4. Apply `ci-cd-and-automation` when changing checks, tasks, or pipelines. -5. Apply `debugging-and-error-recovery` when tests, CI, or runtime behavior fails unexpectedly. -6. Optionally apply `learning-opportunities` for 10-15 minute learning exercises after design-heavy work. +1. Apply `incremental-implementation` for multi-file or higher-risk changes. +1. Apply `code-review-and-quality` as the final quality gate before completion. +1. Apply `ci-cd-and-automation` when changing checks, tasks, or pipelines. +1. Apply `debugging-and-error-recovery` when tests, CI, or runtime behavior fails unexpectedly. +1. Optionally apply `learning-opportunities` for 10-15 minute learning exercises after design-heavy work. ## Local commands