diff --git a/.agents/skills/hookli/SKILL.md b/.agents/skills/hookli/SKILL.md new file mode 100644 index 0000000..066d67d --- /dev/null +++ b/.agents/skills/hookli/SKILL.md @@ -0,0 +1,166 @@ +```markdown +# hookli Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill covers the development patterns, coding conventions, and collaborative workflows for the **hookli** repository—a TypeScript codebase built with Next.js. The project focuses on documenting and demoing custom React hooks, maintaining a design system, and tracking progress with structured documentation and logs. It emphasizes consistent code style, clear commit messages, and streamlined processes for adding features, updating documentation, and enforcing conventions. + +--- + +## Coding Conventions + +### File Naming + +- **Kebab-case** is used for all files, especially in `components/`. + - Example: `use-interval-demo.tsx`, `my-component.tsx` + +### Import Style + +- **Alias imports** are preferred, using configured path aliases. + - Example: + ```typescript + import { useInterval } from '@/lib/hooks/use-interval'; + import Demo from '@/components/demos/use-interval-demo'; + ``` + +### Export Style + +- **Mixed exports**: Both default and named exports are used as appropriate. + - Example: + ```typescript + // Named export + export function useInterval(callback: () => void, delay: number) { ... } + + // Default export + export default DemoComponent; + ``` + +### Commit Messages + +- **Conventional commits**: Use prefixes like `feat`, `chore`, `design`. + - Example: `feat: add useTimeout hook and demo page` +- **Average commit message length**: ~78 characters. + +--- + +## Workflows + +### Add New Hook Doc Page + +**Trigger:** When someone wants to document a new hook for the site. +**Command:** `/add-hook-doc` + +1. Create a demo component: + `components/demos/{hook-name}-demo.tsx` +2. Add a hook entry to: + `lib/hook-docs.ts` +3. Add the hook's source snapshot to: + `lib/hook-sources.ts` +4. Register the hook in: + `lib/hooks-registry.ts` +5. Mark the task as done in: + `ralph/prd.json` +6. Update the progress log: + `ralph/progress.txt` + +**Example:** +```typescript +// components/demos/use-interval-demo.tsx +import { useInterval } from '@/lib/hooks/use-interval'; + +export default function UseIntervalDemo() { + // Demo implementation here +} +``` + +--- + +### Batch Add Multiple Hook Doc Pages + +**Trigger:** When documenting a group of new hooks together. +**Command:** `/batch-add-hook-docs` + +1. For each hook: + - Create demo in `components/demos/{hook-name}-demo.tsx` + - Add entry to `lib/hook-docs.ts` + - Add source to `lib/hook-sources.ts` + - Register in `lib/hooks-registry.ts` +2. Mark all related tasks as done in `ralph/prd.json` +3. Update `ralph/progress.txt` + +--- + +### Feature Development with PRD Tracking + +**Trigger:** When implementing a new feature or completing a tracked task. +**Command:** `/complete-task` + +1. Implement the feature in `app/`, `components/`, or `lib/` as needed. +2. Mark the task as done in `ralph/prd.json`. +3. Log progress in `ralph/progress.txt`. + +--- + +### Design System Token Update + +**Trigger:** When updating design tokens (colors, typography, etc.) or visual style. +**Command:** `/update-design-tokens` + +1. Edit `app/globals.css` to update tokens. +2. Update `docs/DESIGN.md` and/or `AGENTS.md` to reflect changes. +3. Optionally update assets in `public/` (e.g., branding SVGs or PNGs). + +--- + +### Component File Naming Convention Enforcement + +**Trigger:** When enforcing or migrating to kebab-case for component files. +**Command:** `/enforce-kebab-case-components` + +1. Rename all `components/*.tsx` files to kebab-case. +2. Update all imports in `app/`, `components/`, and related files to match new names. +3. Update `AGENTS.md` and/or conventions documentation. + +--- + +### Ralph Progress Logging + +**Trigger:** Whenever a tracked task or batch is completed. +**Command:** `/log-progress` + +1. Edit `ralph/progress.txt` to log the latest progress. + +--- + +## Testing Patterns + +- **Framework:** [vitest](https://vitest.dev/) +- **Test files:** Named with `.test.ts` suffix. + - Example: `use-interval.test.ts` +- **Typical test structure:** + ```typescript + import { describe, it, expect } from 'vitest'; + import { useInterval } from '@/lib/hooks/use-interval'; + + describe('useInterval', () => { + it('calls callback at specified interval', () => { + // Test implementation + }); + }); + ``` + +--- + +## Commands + +| Command | Purpose | +|-------------------------------|----------------------------------------------------------------| +| /add-hook-doc | Add documentation and demo for a new hook | +| /batch-add-hook-docs | Add documentation and demos for multiple hooks in one batch | +| /complete-task | Complete a feature/task and update PRD/progress | +| /update-design-tokens | Update design tokens and sync design documentation | +| /enforce-kebab-case-components| Enforce kebab-case naming for component files and update imports| +| /log-progress | Log progress after completing a task or batch | +``` diff --git a/.agents/skills/hookli/agents/openai.yaml b/.agents/skills/hookli/agents/openai.yaml new file mode 100644 index 0000000..b6c846b --- /dev/null +++ b/.agents/skills/hookli/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Hookli" + short_description: "Repo-specific patterns and workflows for hookli" + default_prompt: "Use the hookli repo skill to follow existing architecture, testing, and workflow conventions." +policy: + allow_implicit_invocation: true \ No newline at end of file diff --git a/.claude/commands/add-new-hook-doc-page.md b/.claude/commands/add-new-hook-doc-page.md new file mode 100644 index 0000000..6ee7f8d --- /dev/null +++ b/.claude/commands/add-new-hook-doc-page.md @@ -0,0 +1,42 @@ +--- +name: add-new-hook-doc-page +description: Workflow command scaffold for add-new-hook-doc-page in hookli. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-new-hook-doc-page + +Use this workflow when working on **add-new-hook-doc-page** in `hookli`. + +## Goal + +Adds documentation for a new React hook, including interactive demo, registry entry, docs metadata, and vendored source snapshot. + +## Common Files + +- `components/demos/{hook-name}-demo.tsx` +- `lib/hook-docs.ts` +- `lib/hook-sources.ts` +- `lib/hooks-registry.ts` +- `ralph/prd.json` +- `ralph/progress.txt` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Create demo component in components/demos/{hook-name}-demo.tsx +- Add hook entry to lib/hook-docs.ts +- Add hook source to lib/hook-sources.ts +- Add hook to lib/hooks-registry.ts +- Update ralph/prd.json to mark the task done + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/batch-add-multiple-hook-doc-pages.md b/.claude/commands/batch-add-multiple-hook-doc-pages.md new file mode 100644 index 0000000..dcbe181 --- /dev/null +++ b/.claude/commands/batch-add-multiple-hook-doc-pages.md @@ -0,0 +1,42 @@ +--- +name: batch-add-multiple-hook-doc-pages +description: Workflow command scaffold for batch-add-multiple-hook-doc-pages in hookli. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /batch-add-multiple-hook-doc-pages + +Use this workflow when working on **batch-add-multiple-hook-doc-pages** in `hookli`. + +## Goal + +Adds documentation for several new hooks in a single commit, following the same steps as adding a single hook doc page, but for multiple hooks at once. + +## Common Files + +- `components/demos/{hook-name}-demo.tsx` +- `lib/hook-docs.ts` +- `lib/hook-sources.ts` +- `lib/hooks-registry.ts` +- `ralph/prd.json` +- `ralph/progress.txt` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- For each hook: create demo component in components/demos/{hook-name}-demo.tsx +- For each hook: add entry to lib/hook-docs.ts +- For each hook: add source to lib/hook-sources.ts +- For each hook: add to lib/hooks-registry.ts +- Update ralph/prd.json to mark all related tasks done + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/commands/feature-development.md b/.claude/commands/feature-development.md new file mode 100644 index 0000000..685413b --- /dev/null +++ b/.claude/commands/feature-development.md @@ -0,0 +1,38 @@ +--- +name: feature-development +description: Workflow command scaffold for feature-development in hookli. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /feature-development + +Use this workflow when working on **feature-development** in `hookli`. + +## Goal + +Standard feature implementation workflow + +## Common Files + +- `app/*` +- `components/*` +- `lib/*` +- `**/api/**` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Add feature implementation +- Add tests for feature +- Update documentation + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file diff --git a/.claude/ecc-tools.json b/.claude/ecc-tools.json new file mode 100644 index 0000000..a1dd434 --- /dev/null +++ b/.claude/ecc-tools.json @@ -0,0 +1,294 @@ +{ + "version": "1.3", + "schemaVersion": "1.0", + "generatedBy": "ecc-tools", + "generatedAt": "2026-07-16T12:43:50.427Z", + "repo": "https://github.com/saifmohamedsv/hookli", + "referenceSetReadiness": { + "score": 29, + "present": 2, + "total": 7, + "items": [ + { + "id": "deep-analyzer-corpus", + "label": "Deep analyzer corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add analyzer fixture, golden, benchmark, or reference-set files that can catch analyzer regressions." + }, + { + "id": "rag-evaluator", + "label": "RAG/evaluator comparison", + "status": "present", + "evidence": [ + "packages/hookli/src/hooks/use-local-storage-with-expiry/use-local-storage-with-expiry.test.ts", + "packages/hookli/src/hooks/use-local-storage/use-local-storage.test.ts", + "packages/hookli/src/hooks/use-read-local-storage/use-read-local-storage.test.ts" + ], + "recommendation": "Add retrieval or evaluator reference-set comparison fixtures with expected ranking behavior." + }, + { + "id": "pr-salvage", + "label": "PR salvage/review corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add stale-PR, review-thread, reopen-flow, or salvage reference cases for queue cleanup automation." + }, + { + "id": "discussion-triage", + "label": "Discussion triage corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add public discussion triage fixtures, golden cases, or reference sets for informational, answered, and no-response classifications." + }, + { + "id": "harness-compatibility", + "label": "Harness compatibility", + "status": "present", + "evidence": [ + ".claude/agents/frontend-code-reviewer.md", + ".claude/agents/product-owner.md", + ".claude/agents/task-orchestrator.md" + ], + "recommendation": "Add cross-harness, adapter-compliance, or harness-audit evidence for Claude, Codex, OpenCode, Zed, dmux, and agent surfaces." + }, + { + "id": "security-evidence", + "label": "Security evidence", + "status": "missing", + "evidence": [], + "recommendation": "Attach security evidence such as SBOMs, SARIF, audit reports, or AgentShield evidence packs." + }, + { + "id": "ci-failure-mode", + "label": "CI failure-mode evidence", + "status": "missing", + "evidence": [], + "recommendation": "Add captured CI failure logs, dry-run fixtures, or troubleshooting docs for common workflow failure modes." + } + ] + }, + "profiles": { + "requested": "developer", + "recommended": "developer", + "effective": "developer", + "requestedAlias": "developer", + "recommendedAlias": "developer", + "effectiveAlias": "developer" + }, + "requestedProfile": "developer", + "profile": "developer", + "recommendedProfile": "developer", + "effectiveProfile": "developer", + "tier": "free", + "requestedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "selectedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "requestedAddComponents": [], + "requestedRemoveComponents": [], + "blockedRemovalComponents": [], + "tierFilteredComponents": [], + "requestedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "selectedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedAddPackages": [], + "requestedRemovePackages": [], + "selectedPackages": [ + "runtime-core", + "workflow-pack" + ], + "packages": [ + "runtime-core", + "workflow-pack" + ], + "blockedRemovalPackages": [], + "tierFilteredRootPackages": [], + "tierFilteredPackages": [], + "conflictingPackages": [], + "dependencyGraph": { + "runtime-core": [], + "workflow-pack": [ + "runtime-core" + ] + }, + "resolutionOrder": [ + "runtime-core", + "workflow-pack" + ], + "requestedModules": [ + "runtime-core", + "workflow-pack" + ], + "selectedModules": [ + "runtime-core", + "workflow-pack" + ], + "modules": [ + "runtime-core", + "workflow-pack" + ], + "managedFiles": [ + ".claude/skills/hookli/SKILL.md", + ".agents/skills/hookli/SKILL.md", + ".agents/skills/hookli/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/hookli-instincts.yaml", + ".claude/commands/feature-development.md", + ".claude/commands/add-new-hook-doc-page.md", + ".claude/commands/batch-add-multiple-hook-doc-pages.md" + ], + "packageFiles": { + "runtime-core": [ + ".claude/skills/hookli/SKILL.md", + ".agents/skills/hookli/SKILL.md", + ".agents/skills/hookli/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/hookli-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/add-new-hook-doc-page.md", + ".claude/commands/batch-add-multiple-hook-doc-pages.md" + ] + }, + "moduleFiles": { + "runtime-core": [ + ".claude/skills/hookli/SKILL.md", + ".agents/skills/hookli/SKILL.md", + ".agents/skills/hookli/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/hookli-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/feature-development.md", + ".claude/commands/add-new-hook-doc-page.md", + ".claude/commands/batch-add-multiple-hook-doc-pages.md" + ] + }, + "files": [ + { + "moduleId": "runtime-core", + "path": ".claude/skills/hookli/SKILL.md", + "description": "Repository-specific Claude Code skill generated from git history." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/hookli/SKILL.md", + "description": "Codex-facing copy of the generated repository skill." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/hookli/agents/openai.yaml", + "description": "Codex skill metadata so the repo skill appears cleanly in the skill interface." + }, + { + "moduleId": "runtime-core", + "path": ".claude/identity.json", + "description": "Suggested identity.json baseline derived from repository conventions." + }, + { + "moduleId": "runtime-core", + "path": ".codex/config.toml", + "description": "Repo-local Codex MCP and multi-agent baseline aligned with ECC defaults." + }, + { + "moduleId": "runtime-core", + "path": ".codex/AGENTS.md", + "description": "Codex usage guide that points at the generated repo skill and workflow bundle." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/explorer.toml", + "description": "Read-only explorer role config for Codex multi-agent work." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/reviewer.toml", + "description": "Read-only reviewer role config focused on correctness and security." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/docs-researcher.toml", + "description": "Read-only docs researcher role config for API verification." + }, + { + "moduleId": "runtime-core", + "path": ".claude/homunculus/instincts/inherited/hookli-instincts.yaml", + "description": "Continuous-learning instincts derived from repository patterns." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/feature-development.md", + "description": "Workflow command scaffold for feature-development." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/add-new-hook-doc-page.md", + "description": "Workflow command scaffold for add-new-hook-doc-page." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/batch-add-multiple-hook-doc-pages.md", + "description": "Workflow command scaffold for batch-add-multiple-hook-doc-pages." + } + ], + "workflows": [ + { + "command": "feature-development", + "path": ".claude/commands/feature-development.md" + }, + { + "command": "add-new-hook-doc-page", + "path": ".claude/commands/add-new-hook-doc-page.md" + }, + { + "command": "batch-add-multiple-hook-doc-pages", + "path": ".claude/commands/batch-add-multiple-hook-doc-pages.md" + } + ], + "adapters": { + "claudeCode": { + "skillPath": ".claude/skills/hookli/SKILL.md", + "identityPath": ".claude/identity.json", + "commandPaths": [ + ".claude/commands/feature-development.md", + ".claude/commands/add-new-hook-doc-page.md", + ".claude/commands/batch-add-multiple-hook-doc-pages.md" + ] + }, + "codex": { + "configPath": ".codex/config.toml", + "agentsGuidePath": ".codex/AGENTS.md", + "skillPath": ".agents/skills/hookli/SKILL.md" + } + } +} \ No newline at end of file diff --git a/.claude/homunculus/instincts/inherited/hookli-instincts.yaml b/.claude/homunculus/instincts/inherited/hookli-instincts.yaml new file mode 100644 index 0000000..58f3c36 --- /dev/null +++ b/.claude/homunculus/instincts/inherited/hookli-instincts.yaml @@ -0,0 +1,693 @@ +# Instincts generated from https://github.com/saifmohamedsv/hookli +# Generated: 2026-07-16T12:44:33.493Z +# Version: 2.0 +# NOTE: This file supplements (does not replace) any existing curated instincts. +# High-confidence manually curated instincts should be preserved alongside these. + +--- +id: hookli-commit-conventional +trigger: "when writing a commit message" +confidence: 0.85 +domain: git +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Commit Conventional + +## Action + +Use conventional commit format with prefixes: feat, chore, design + +## Evidence + +- 63 commits analyzed +- Detected conventional commit pattern +- Examples: chore: seed hookli-docs — scaffold + ralph harness + T1-T15 backlog, feat(site): T1 — research benchmarks, write docs/DESIGN.md design source of truth + +--- +id: hookli-commit-length +trigger: "when writing a commit message" +confidence: 0.6 +domain: git +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Commit Length + +## Action + +Write moderate-length commit messages (~78 characters) + +## Evidence + +- Average commit message length: 78 chars +- Based on 63 commits + +--- +id: hookli-naming-files +trigger: "when creating a new file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Naming Files + +## Action + +Use kebab-case naming convention + +## Evidence + +- Analyzed file naming patterns in repository +- Dominant pattern: kebab-case + +--- +id: hookli-import-alias +trigger: "when importing modules" +confidence: 0.85 +domain: code-style +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Import Alias + +## Action + +Use path aliases (@/, ~/) instead of relative imports + +## Evidence + +- Import analysis shows alias pattern +- Example: import { x } from '@/lib/x' + +--- +id: hookli-export-style +trigger: "when exporting from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Export Style + +## Action + +Prefer mixed exports + +## Evidence + +- Export pattern analysis +- Dominant style: mixed + +--- +id: hookli-arch-type-based +trigger: "when adding new code" +confidence: 0.8 +domain: architecture +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Arch Type Based + +## Action + +Place code in the appropriate type folder (components/, services/, utils/, etc.) + +## Evidence + +- Type-based module organization detected +- Folders: + +--- +id: hookli-test-framework +trigger: "when writing tests" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Test Framework + +## Action + +Use vitest as the test framework + +## Evidence + +- Test framework detected: vitest +- File pattern: *.test.ts + +--- +id: hookli-test-naming +trigger: "when creating a test file" +confidence: 0.85 +domain: testing +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Test Naming + +## Action + +Name test files using the pattern: *.test.ts + +## Evidence + +- File pattern: *.test.ts +- Consistent across test files + +--- +id: hookli-test-types +trigger: "when planning tests for a feature" +confidence: 0.7 +domain: testing +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Test Types + +## Action + +Write unit, integration tests to match project standards + +## Evidence + +- Test types detected: unit, integration +- Coverage config: no + +--- +id: hookli-workflow-feature-development +trigger: "when implementing a new feature" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Workflow Feature Development + +## Action + +Follow the feature-development workflow: +1. Add feature implementation +2. Add tests for feature +3. Update documentation + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~20x per month +- Files: app/*, components/*, lib/* + +--- +id: hookli-workflow-add-new-hook-doc-page +trigger: "when doing add new hook doc page" +confidence: 0.75 +domain: workflow +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Workflow Add New Hook Doc Page + +## Action + +Follow the add-new-hook-doc-page workflow: +1. Create demo component in components/demos/{hook-name}-demo.tsx +2. Add hook entry to lib/hook-docs.ts +3. Add hook source to lib/hook-sources.ts +4. Add hook to lib/hooks-registry.ts +5. Update ralph/prd.json to mark the task done +6. Update ralph/progress.txt + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~5x per month +- Files: components/demos/{hook-name}-demo.tsx, lib/hook-docs.ts, lib/hook-sources.ts + +--- +id: hookli-workflow-batch-add-multiple-hook-doc-pages +trigger: "when doing batch add multiple hook doc pages" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Workflow Batch Add Multiple Hook Doc Pages + +## Action + +Follow the batch-add-multiple-hook-doc-pages workflow: +1. For each hook: create demo component in components/demos/{hook-name}-demo.tsx +2. For each hook: add entry to lib/hook-docs.ts +3. For each hook: add source to lib/hook-sources.ts +4. For each hook: add to lib/hooks-registry.ts +5. Update ralph/prd.json to mark all related tasks done +6. Update ralph/progress.txt + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: components/demos/{hook-name}-demo.tsx, lib/hook-docs.ts, lib/hook-sources.ts + +--- +id: hookli-workflow-feature-development-with-prd-tracking +trigger: "when doing feature development with prd tracking" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Workflow Feature Development With Prd Tracking + +## Action + +Follow the feature-development-with-prd-tracking workflow: +1. Implement feature (code in app/, components/, lib/ as needed) +2. Update ralph/prd.json to mark the task done +3. Update ralph/progress.txt + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~15x per month +- Files: app/**/*.tsx, components/**/*.tsx, lib/**/*.ts + +--- +id: hookli-workflow-design-system-token-update +trigger: "when doing design system token update" +confidence: 0.65 +domain: workflow +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Workflow Design System Token Update + +## Action + +Follow the design-system-token-update workflow: +1. Edit app/globals.css to update tokens +2. Update docs/DESIGN.md and/or AGENTS.md to reflect changes +3. Optionally update public/ assets if branding changes + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~3x per month +- Files: app/globals.css, docs/DESIGN.md, AGENTS.md + +--- +id: hookli-workflow-component-file-naming-convention-enforcement +trigger: "when doing component file naming convention enforcement" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Workflow Component File Naming Convention Enforcement + +## Action + +Follow the component-file-naming-convention-enforcement workflow: +1. Rename components/*.tsx files to kebab-case +2. Update all imports in app/, components/, and related files to match new names +3. Update AGENTS.md and/or conventions documentation + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: components/*.tsx, app/**/*.tsx, AGENTS.md + +--- +id: hookli-workflow-ralph-progress-logging +trigger: "when doing ralph progress logging" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/saifmohamedsv/hookli +--- + +# Hookli Workflow Ralph Progress Logging + +## Action + +Follow the ralph-progress-logging workflow: +1. Edit ralph/progress.txt to log progress + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~10x per month +- Files: ralph/progress.txt + +--- +id: hookli-kebab-case-file-names +trigger: "When creating or renaming a file in components/ or app/" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Kebab Case File Names + +## Action + +Name the file using kebab-case (e.g., my-component.tsx) + +## Evidence + +- docs(conventions): correct to Nzmly kebab-case style; fix T18/T19 backlog +- Pattern in namingConventions.files = kebab-case +- component-file-naming-convention-enforcement workflow + +--- +id: hookli-camel-case-functions +trigger: "When defining a function" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Camel Case Functions + +## Action + +Name the function using camelCase + +## Evidence + +- Pattern in namingConventions.functions = camelCase + +--- +id: hookli-pascal-case-classes +trigger: "When defining a class" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Pascal Case Classes + +## Action + +Name the class using PascalCase + +## Evidence + +- Pattern in namingConventions.classes = PascalCase + +--- +id: hookli-screaming-snake-case-constants +trigger: "When defining a constant" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Screaming Snake Case Constants + +## Action + +Name the constant using SCREAMING_SNAKE_CASE + +## Evidence + +- Pattern in namingConventions.constants = SCREAMING_SNAKE_CASE + +--- +id: hookli-alias-imports +trigger: "When importing modules" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Alias Imports + +## Action + +Use import aliases as defined in tsconfig.json or project config + +## Evidence + +- Pattern in importStyle = alias +- Presence of tsconfig.json paths + +--- +id: hookli-mixed-export-style +trigger: "When exporting modules" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Mixed Export Style + +## Action + +Use both default and named exports as appropriate + +## Evidence + +- Pattern in exportStyle = mixed + +--- +id: hookli-vitest-test-pattern +trigger: "When writing tests for TypeScript code" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Vitest Test Pattern + +## Action + +Place tests in files matching *.test.ts and use Vitest framework + +## Evidence + +- Pattern in testing.framework = vitest +- Pattern in testing.filePattern = *.test.ts + +--- +id: hookli-unit-and-integration-tests +trigger: "When testing a feature or module" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Unit And Integration Tests + +## Action + +Write both unit and integration tests as appropriate + +## Evidence + +- Pattern in testing.testTypes = unit, integration + +--- +id: hookli-no-coverage-config +trigger: "When configuring test coverage" +confidence: 0.6 +domain: testing +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli No Coverage Config + +## Action + +Do not enforce coverage configuration (coverageConfig: false) + +## Evidence + +- Pattern in testing.coverageConfig = false + +--- +id: hookli-conventional-commits +trigger: "When writing a commit message" +confidence: 0.9 +domain: git +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Conventional Commits + +## Action + +Use conventional commit prefixes (feat, chore, design, docs) and format + +## Evidence + +- Pattern in commits.type = conventional +- Examples: feat(site): ..., chore: ..., design: ... + +--- +id: hookli-commit-length +trigger: "When writing a commit message" +confidence: 0.7 +domain: git +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Commit Length + +## Action + +Keep the commit message concise (~78 characters on average) + +## Evidence + +- Pattern in commits.averageLength = 78 + +--- +id: hookli-add-new-hook-doc-page +trigger: "When someone wants to document a new hook for the site" +confidence: 0.98 +domain: workflow +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Add New Hook Doc Page + +## Action + +Create demo in components/demos/{hook-name}-demo.tsx, update lib/hook-docs.ts, lib/hook-sources.ts, lib/hooks-registry.ts, ralph/prd.json, and ralph/progress.txt + +## Evidence + +- add-new-hook-doc-page workflow +- Multiple batches in commit history + +--- +id: hookli-batch-add-multiple-hook-doc-pages +trigger: "When someone wants to document a group of new hooks together" +confidence: 0.97 +domain: workflow +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Batch Add Multiple Hook Doc Pages + +## Action + +For each hook: create demo, update docs, sources, registry, and tracking files in a batch + +## Evidence + +- batch-add-multiple-hook-doc-pages workflow +- Batch commits in history + +--- +id: hookli-feature-development-with-prd-tracking +trigger: "When working on a new feature or task tracked in the product requirements doc" +confidence: 0.92 +domain: workflow +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Feature Development With Prd Tracking + +## Action + +Implement feature in app/, components/, lib/ and update ralph/prd.json and ralph/progress.txt + +## Evidence + +- feature-development-with-prd-tracking workflow +- Seen in commit sequences for features + +--- +id: hookli-design-system-token-update +trigger: "When changing the design system's core tokens or visual style" +confidence: 0.88 +domain: workflow +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Design System Token Update + +## Action + +Edit app/globals.css, update docs/DESIGN.md and/or AGENTS.md, and update public/ assets if branding changes + +## Evidence + +- design-system-token-update workflow +- Commits referencing globals.css and DESIGN.md + +--- +id: hookli-component-file-naming-convention-enforcement +trigger: "When enforcing or migrating to kebab-case for component files" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Component File Naming Convention Enforcement + +## Action + +Rename components/*.tsx to kebab-case, update imports, and update AGENTS.md or conventions docs + +## Evidence + +- component-file-naming-convention-enforcement workflow +- docs(conventions): correct to Nzmly kebab-case style; fix T18/T19 backlog + +--- +id: hookli-ralph-progress-logging +trigger: "Whenever a tracked task is finished or a batch of work is completed" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: saifmohamedsv/hookli +--- + +# Hookli Ralph Progress Logging + +## Action + +Edit ralph/progress.txt to log progress + +## Evidence + +- ralph-progress-logging workflow +- Frequent commits updating ralph/progress.txt + diff --git a/.claude/identity.json b/.claude/identity.json new file mode 100644 index 0000000..5645f5e --- /dev/null +++ b/.claude/identity.json @@ -0,0 +1,15 @@ +{ + "version": "2.0", + "technicalLevel": "technical", + "preferredStyle": { + "verbosity": "minimal", + "codeComments": true, + "explanations": true + }, + "domains": [ + "typescript", + "next.js" + ], + "suggestedBy": "ecc-tools-repo-analysis", + "createdAt": "2026-07-16T12:44:33.493Z" +} \ No newline at end of file diff --git a/.claude/skills/hookli/SKILL.md b/.claude/skills/hookli/SKILL.md new file mode 100644 index 0000000..066d67d --- /dev/null +++ b/.claude/skills/hookli/SKILL.md @@ -0,0 +1,166 @@ +```markdown +# hookli Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill covers the development patterns, coding conventions, and collaborative workflows for the **hookli** repository—a TypeScript codebase built with Next.js. The project focuses on documenting and demoing custom React hooks, maintaining a design system, and tracking progress with structured documentation and logs. It emphasizes consistent code style, clear commit messages, and streamlined processes for adding features, updating documentation, and enforcing conventions. + +--- + +## Coding Conventions + +### File Naming + +- **Kebab-case** is used for all files, especially in `components/`. + - Example: `use-interval-demo.tsx`, `my-component.tsx` + +### Import Style + +- **Alias imports** are preferred, using configured path aliases. + - Example: + ```typescript + import { useInterval } from '@/lib/hooks/use-interval'; + import Demo from '@/components/demos/use-interval-demo'; + ``` + +### Export Style + +- **Mixed exports**: Both default and named exports are used as appropriate. + - Example: + ```typescript + // Named export + export function useInterval(callback: () => void, delay: number) { ... } + + // Default export + export default DemoComponent; + ``` + +### Commit Messages + +- **Conventional commits**: Use prefixes like `feat`, `chore`, `design`. + - Example: `feat: add useTimeout hook and demo page` +- **Average commit message length**: ~78 characters. + +--- + +## Workflows + +### Add New Hook Doc Page + +**Trigger:** When someone wants to document a new hook for the site. +**Command:** `/add-hook-doc` + +1. Create a demo component: + `components/demos/{hook-name}-demo.tsx` +2. Add a hook entry to: + `lib/hook-docs.ts` +3. Add the hook's source snapshot to: + `lib/hook-sources.ts` +4. Register the hook in: + `lib/hooks-registry.ts` +5. Mark the task as done in: + `ralph/prd.json` +6. Update the progress log: + `ralph/progress.txt` + +**Example:** +```typescript +// components/demos/use-interval-demo.tsx +import { useInterval } from '@/lib/hooks/use-interval'; + +export default function UseIntervalDemo() { + // Demo implementation here +} +``` + +--- + +### Batch Add Multiple Hook Doc Pages + +**Trigger:** When documenting a group of new hooks together. +**Command:** `/batch-add-hook-docs` + +1. For each hook: + - Create demo in `components/demos/{hook-name}-demo.tsx` + - Add entry to `lib/hook-docs.ts` + - Add source to `lib/hook-sources.ts` + - Register in `lib/hooks-registry.ts` +2. Mark all related tasks as done in `ralph/prd.json` +3. Update `ralph/progress.txt` + +--- + +### Feature Development with PRD Tracking + +**Trigger:** When implementing a new feature or completing a tracked task. +**Command:** `/complete-task` + +1. Implement the feature in `app/`, `components/`, or `lib/` as needed. +2. Mark the task as done in `ralph/prd.json`. +3. Log progress in `ralph/progress.txt`. + +--- + +### Design System Token Update + +**Trigger:** When updating design tokens (colors, typography, etc.) or visual style. +**Command:** `/update-design-tokens` + +1. Edit `app/globals.css` to update tokens. +2. Update `docs/DESIGN.md` and/or `AGENTS.md` to reflect changes. +3. Optionally update assets in `public/` (e.g., branding SVGs or PNGs). + +--- + +### Component File Naming Convention Enforcement + +**Trigger:** When enforcing or migrating to kebab-case for component files. +**Command:** `/enforce-kebab-case-components` + +1. Rename all `components/*.tsx` files to kebab-case. +2. Update all imports in `app/`, `components/`, and related files to match new names. +3. Update `AGENTS.md` and/or conventions documentation. + +--- + +### Ralph Progress Logging + +**Trigger:** Whenever a tracked task or batch is completed. +**Command:** `/log-progress` + +1. Edit `ralph/progress.txt` to log the latest progress. + +--- + +## Testing Patterns + +- **Framework:** [vitest](https://vitest.dev/) +- **Test files:** Named with `.test.ts` suffix. + - Example: `use-interval.test.ts` +- **Typical test structure:** + ```typescript + import { describe, it, expect } from 'vitest'; + import { useInterval } from '@/lib/hooks/use-interval'; + + describe('useInterval', () => { + it('calls callback at specified interval', () => { + // Test implementation + }); + }); + ``` + +--- + +## Commands + +| Command | Purpose | +|-------------------------------|----------------------------------------------------------------| +| /add-hook-doc | Add documentation and demo for a new hook | +| /batch-add-hook-docs | Add documentation and demos for multiple hooks in one batch | +| /complete-task | Complete a feature/task and update PRD/progress | +| /update-design-tokens | Update design tokens and sync design documentation | +| /enforce-kebab-case-components| Enforce kebab-case naming for component files and update imports| +| /log-progress | Log progress after completing a task or batch | +``` diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 0000000..442325b --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,28 @@ +# ECC for Codex CLI + +This supplements the root `AGENTS.md` with a repo-local ECC baseline. + +## Repo Skill + +- Repo-generated Codex skill: `.agents/skills/hookli/SKILL.md` +- Claude-facing companion skill: `.claude/skills/hookli/SKILL.md` +- Keep user-specific credentials and private MCPs in `~/.codex/config.toml`, not in this repo. + +## MCP Baseline + +Treat `.codex/config.toml` as the default ECC-safe baseline for work in this repository. +The generated baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking. + +## Multi-Agent Support + +- Explorer: read-only evidence gathering +- Reviewer: correctness, security, and regression review +- Docs researcher: API and release-note verification + +## Workflow Files + +- `.claude/commands/feature-development.md` +- `.claude/commands/add-new-hook-doc-page.md` +- `.claude/commands/batch-add-multiple-hook-doc-pages.md` + +Use these workflow files as reusable task scaffolds when the detected repository workflows recur. \ No newline at end of file diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.toml new file mode 100644 index 0000000..0daae57 --- /dev/null +++ b/.codex/agents/docs-researcher.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Verify APIs, framework behavior, and release-note claims against primary documentation before changes land. +Cite the exact docs or file paths that support each claim. +Do not invent undocumented behavior. +""" \ No newline at end of file diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml new file mode 100644 index 0000000..732df7a --- /dev/null +++ b/.codex/agents/explorer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Stay in exploration mode. +Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them. +Prefer targeted search and file reads over broad scans. +""" \ No newline at end of file diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 0000000..b13ed9c --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "high" +sandbox_mode = "read-only" + +developer_instructions = """ +Review like an owner. +Prioritize correctness, security, behavioral regressions, and missing tests. +Lead with concrete findings and avoid style-only feedback unless it hides a real bug. +""" \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..bc1ee67 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,48 @@ +#:schema https://developers.openai.com/codex/config-schema.json + +# ECC Tools generated Codex baseline +approval_policy = "on-request" +sandbox_mode = "workspace-write" +web_search = "live" + +[mcp_servers.github] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-github"] + +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp@latest"] + +[mcp_servers.exa] +url = "https://mcp.exa.ai/mcp" + +[mcp_servers.memory] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-memory"] + +[mcp_servers.playwright] +command = "npx" +args = ["-y", "@playwright/mcp@latest", "--extension"] + +[mcp_servers.sequential-thinking] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-sequential-thinking"] + +[features] +multi_agent = true + +[agents] +max_threads = 6 +max_depth = 1 + +[agents.explorer] +description = "Read-only codebase explorer for gathering evidence before changes are proposed." +config_file = "agents/explorer.toml" + +[agents.reviewer] +description = "PR reviewer focused on correctness, security, and missing tests." +config_file = "agents/reviewer.toml" + +[agents.docs_researcher] +description = "Documentation specialist that verifies APIs, framework behavior, and release notes." +config_file = "agents/docs-researcher.toml" \ No newline at end of file