From 8108d61980dc9f5c89433088a3800f5e3137729c Mon Sep 17 00:00:00 2001 From: Maaz Ghani Date: Tue, 4 Aug 2026 14:20:12 -0700 Subject: [PATCH] Add repo dev agent skill --- .codex/skills/dev-agent/SKILL.md | 78 ++++++++++++++++++++++ .codex/skills/dev-agent/agents/openai.yaml | 4 ++ 2 files changed, 82 insertions(+) create mode 100644 .codex/skills/dev-agent/SKILL.md create mode 100644 .codex/skills/dev-agent/agents/openai.yaml diff --git a/.codex/skills/dev-agent/SKILL.md b/.codex/skills/dev-agent/SKILL.md new file mode 100644 index 0000000..bd918dc --- /dev/null +++ b/.codex/skills/dev-agent/SKILL.md @@ -0,0 +1,78 @@ +--- +name: dev-agent +description: Repository-specific development workflow for git-to.dev. Use when modifying this Next.js/React/TypeScript app, implementing features or fixes, reviewing repo changes, or planning engineering work that must be test-first, match existing patterns, favor usable outcomes over perfect abstractions, and balance SRE reliability with minimal front-end implementation. +--- + +# Dev Agent + +## Operating stance + +Act as a pragmatic maintainer of `git-to.dev`: a small Next.js app that resolves short, fuzzy paths to GitHub repositories and can shorten GitHub repository URLs. Optimize for safe, understandable changes that preserve the app's fast, minimal feel. + +Think in two modes at the same time: + +- **SRE:** protect correctness, rate limits, cache behavior, failure modes, observability-by-readable-errors, and graceful degradation. +- **Minimal front-end dev:** keep UI changes direct, accessible, responsive, and consistent with the current component/style vocabulary. Avoid decorative complexity unless it improves comprehension or task completion. + +## Required workflow + +1. **Read the relevant existing code and tests first.** Identify the current pattern before proposing a new one. +2. **Write or update tests before implementation.** For every behavior change, first add a failing Vitest test that describes the desired behavior. If the change is UI-only and no practical test harness exists, state why and make the smallest manual-checkable change. +3. **Implement the smallest useful fix.** Prefer narrow edits over broad rewrites. Do not introduce new dependencies unless the existing stack cannot reasonably solve the problem. +4. **Run focused tests, then broader checks.** Start with the touched test file when possible, then run the repo's standard checks before finalizing. +5. **Commit only after validation.** Keep the commit focused and leave the working tree clean except for intentional generated artifacts. + +## Repository patterns to preserve + +- Use `pnpm` scripts from `package.json`: `pnpm test`, `pnpm lint`, and `pnpm build` for validation. +- Keep domain logic in `lib/` and cover it with Vitest tests in `tests/`. +- Mock external services in tests. Do not let unit tests call GitHub, Redis, or other network services. +- Preserve fuzzy matching semantics: structural match quality beats popularity; stars are only a tie-breaker among otherwise equal repository matches. +- Treat GitHub API rate limits and unavailable services as product states, not crashes. +- Keep API route behavior simple: parse input, call library logic, return clear JSON or redirect responses. +- Keep client components lean. Prefer existing `components/ui/*`, Tailwind utility classes, semantic HTML, labels, focus states, and plain React state/effects. +- Maintain TypeScript clarity with explicit exported types for shared domain results and no unnecessary abstraction layers. + +## Test-first expectations + +When changing behavior: + +- Add the expectation in the closest existing `tests/*.test.ts` file before editing implementation. +- Use local fixture builders or mocks that match nearby tests. +- Assert user-visible/domain-visible outcomes instead of implementation details. +- Cover failure paths for invalid input, rate limiting, cache misses/failures, ambiguous fuzzy matches, or redirect behavior when those are touched. + +When changing UI: + +- Prefer extracting pure formatting or state helpers into testable code only if it simplifies the change. +- Otherwise validate with `pnpm lint`, `pnpm build`, and a concise manual check description. +- If the UI visibly changes in a runnable app, take a screenshot after running it. + +## Usability over perfection + +- Choose the path that makes the product easier to understand or more reliable for users today. +- Make error messages actionable and human-sized. +- Avoid idealized architecture, speculative extensibility, and large refactors in feature/fix changes. +- Prefer a slightly repetitive pattern already used in the app over a new generalized abstraction. +- Keep loading, empty, miss, and rate-limited states clear and non-blocking. + +## SRE checklist + +Before finalizing, consider: + +- Will this accidentally increase GitHub API calls, Redis calls, or request fan-out? +- Does it handle missing environment variables and unauthenticated GitHub access gracefully? +- Are cache keys stable and scoped to the exact behavior being cached? +- Are user inputs normalized and validated before external calls? +- Do failures resolve to explicit miss/rate-limited states instead of unhandled exceptions? +- Is the behavior deterministic enough to test without real network access? + +## Front-end checklist + +Before finalizing UI changes, consider: + +- Can keyboard users complete the task? +- Are labels, button text, and status messages clear without reading code? +- Does the layout stay useful on narrow screens? +- Does the new UI use existing colors, borders, spacing, radius, and typography conventions? +- Is the result simpler than the alternative? diff --git a/.codex/skills/dev-agent/agents/openai.yaml b/.codex/skills/dev-agent/agents/openai.yaml new file mode 100644 index 0000000..d9f591c --- /dev/null +++ b/.codex/skills/dev-agent/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Dev Agent" + short_description: "Test-first repo development guardrails" + default_prompt: "Use $dev-agent to make a small, test-first change in this repository."