diff --git a/.agents/skills/skills/SKILL.md b/.agents/skills/skills/SKILL.md new file mode 100644 index 0000000..8e3a797 --- /dev/null +++ b/.agents/skills/skills/SKILL.md @@ -0,0 +1,111 @@ +```markdown +# skills Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This repository demonstrates best practices for developing modular Python "skills" without a framework. It emphasizes clear documentation, consistent coding conventions, and structured workflows for adding, enhancing, and documenting skill packages. The patterns here are ideal for maintainable, collaborative Python codebases. + +## Coding Conventions + +- **File Naming:** + Use PascalCase for Python files and directories. + *Example:* + ``` + CodexCrossProviderSessionRepair/ + RepairSession.py + ``` + +- **Import Style:** + Use relative imports within skill packages. + *Example:* + ```python + from .RepairSession import RepairSession + ``` + +- **Export Style:** + Use named exports (explicitly define what is exported). + *Example:* + ```python + __all__ = ["RepairSession"] + ``` + +- **Commit Messages:** + Follow the [Conventional Commits](https://www.conventionalcommits.org/) style. + - Prefixes: `docs`, `feat` + - Example: + ``` + docs: update SKILL.md with new workflow + feat: add session repair logic + ``` + +## Workflows + +### update-documentation-files +**Trigger:** When you want to improve, clarify, or add documentation for the repository or a skill. +**Command:** `/update-docs` + +1. Edit or add content to `README.md` at the root or within a skill directory. +2. Optionally update or add language-specific README files (e.g., `README.zh-CN.md`). +3. Update `CHANGELOG.md` and/or `SKILL.md` as needed. +4. Commit changes with a `docs:`-prefixed message. + +*Example:* +```bash +# Edit documentation files +git add codex-cross-provider-session-repair/README.md +git commit -m "docs: clarify session repair steps" +``` + +--- + +### add-or-enhance-skill-package +**Trigger:** When you want to introduce a new skill or make significant updates to an existing skill's implementation and documentation. +**Command:** `/add-skill` + +1. Create or update the skill directory with necessary files (`README.md`, `SKILL.md`, scripts, tests, etc.). +2. Add or update scripts (e.g., `install.sh`, `package.py`, `repair.py`). +3. Update or add tests in the `tests/` subdirectory. +4. Update documentation files within the skill (`README.md`, `CHANGELOG.md`, `SKILL.md`, etc.). +5. Commit all changes together. + +*Example:* +```bash +# Add a new skill +mkdir codex-cross-provider-session-repair +touch codex-cross-provider-session-repair/README.md +touch codex-cross-provider-session-repair/SKILL.md +touch codex-cross-provider-session-repair/scripts/repair.py +mkdir codex-cross-provider-session-repair/tests +touch codex-cross-provider-session-repair/tests/test_repair.py + +git add codex-cross-provider-session-repair/ +git commit -m "feat: add codex cross-provider session repair skill" +``` + +## Testing Patterns + +- **Framework:** Not explicitly specified; use standard Python testing practices. +- **Test File Pattern:** Name test files as `*.test.*` or place them in a `tests/` subdirectory. +- **Example:** + ``` + codex-cross-provider-session-repair/tests/test_repair.py + ``` +- **Typical Test Structure:** + ```python + import unittest + from ..scripts.repair import repair_session + + class TestRepairSession(unittest.TestCase): + def test_repair(self): + self.assertTrue(repair_session()) + ``` + +## Commands + +| Command | Purpose | +|--------------|---------------------------------------------------------------| +| /update-docs | Update documentation files (README, SKILL.md, CHANGELOG, etc) | +| /add-skill | Add or enhance a skill package with code, tests, and docs | +``` diff --git a/.agents/skills/skills/agents/openai.yaml b/.agents/skills/skills/agents/openai.yaml new file mode 100644 index 0000000..786b0b9 --- /dev/null +++ b/.agents/skills/skills/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Skills" + short_description: "Repo-specific patterns and workflows for skills" + default_prompt: "Use the skills 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-or-enhance-skill-package.md b/.claude/commands/add-or-enhance-skill-package.md new file mode 100644 index 0000000..6fd4c31 --- /dev/null +++ b/.claude/commands/add-or-enhance-skill-package.md @@ -0,0 +1,42 @@ +--- +name: add-or-enhance-skill-package +description: Workflow command scaffold for add-or-enhance-skill-package in skills. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-or-enhance-skill-package + +Use this workflow when working on **add-or-enhance-skill-package** in `skills`. + +## Goal + +Adds a new skill package or enhances an existing one by updating code, scripts, tests, and documentation within the skill directory. + +## Common Files + +- `codex-cross-provider-session-repair/README.md` +- `codex-cross-provider-session-repair/SKILL.md` +- `codex-cross-provider-session-repair/CHANGELOG.md` +- `codex-cross-provider-session-repair/scripts/install.sh` +- `codex-cross-provider-session-repair/scripts/package.py` +- `codex-cross-provider-session-repair/scripts/repair.py` + +## 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 or update the skill directory with necessary files (README, SKILL.md, scripts, tests, etc.) +- Add or update scripts (e.g., install.sh, package.py, repair.py) +- Update or add tests in the tests/ subdirectory +- Update documentation files within the skill (README.md, CHANGELOG.md, SKILL.md, etc.) +- Commit all changes together + +## 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/update-documentation-files.md b/.claude/commands/update-documentation-files.md new file mode 100644 index 0000000..acc15cb --- /dev/null +++ b/.claude/commands/update-documentation-files.md @@ -0,0 +1,40 @@ +--- +name: update-documentation-files +description: Workflow command scaffold for update-documentation-files in skills. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /update-documentation-files + +Use this workflow when working on **update-documentation-files** in `skills`. + +## Goal + +Updates documentation files for the repository or a specific skill, including README, CHANGELOG, and related markdown files. + +## Common Files + +- `README.md` +- `codex-cross-provider-session-repair/README.md` +- `codex-cross-provider-session-repair/README.zh-CN.md` +- `codex-cross-provider-session-repair/CHANGELOG.md` +- `codex-cross-provider-session-repair/SKILL.md` + +## 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 + +- Edit or add content to README.md at the root or within a skill directory +- Optionally update or add language-specific README files (e.g., README.zh-CN.md) +- Update CHANGELOG.md and/or SKILL.md as needed +- Commit changes with a docs-related message + +## 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..7337366 --- /dev/null +++ b/.claude/ecc-tools.json @@ -0,0 +1,306 @@ +{ + "version": "1.3", + "schemaVersion": "1.0", + "generatedBy": "ecc-tools", + "generatedAt": "2026-08-01T06:52:11.883Z", + "repo": "https://github.com/WardLu/skills", + "referenceSetReadiness": { + "score": 14, + "present": 1, + "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": "missing", + "evidence": [], + "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": "missing", + "evidence": [], + "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": "present", + "evidence": [ + "codex-cross-provider-session-repair/SECURITY.md" + ], + "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": "full", + "recommended": "full", + "effective": "developer", + "requestedAlias": "full", + "recommendedAlias": "full", + "effectiveAlias": "developer" + }, + "requestedProfile": "full", + "profile": "developer", + "recommendedProfile": "full", + "effectiveProfile": "developer", + "tier": "free", + "requestedComponents": [ + "repo-baseline", + "workflow-automation", + "security-audits", + "research-tooling", + "team-rollout", + "governance-controls" + ], + "selectedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "requestedAddComponents": [], + "requestedRemoveComponents": [], + "blockedRemovalComponents": [], + "tierFilteredComponents": [ + "security-audits", + "research-tooling", + "team-rollout", + "governance-controls" + ], + "requestedRootPackages": [ + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "selectedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedPackages": [ + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "requestedAddPackages": [], + "requestedRemovePackages": [], + "selectedPackages": [ + "runtime-core", + "workflow-pack" + ], + "packages": [ + "runtime-core", + "workflow-pack" + ], + "blockedRemovalPackages": [], + "tierFilteredRootPackages": [ + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "tierFilteredPackages": [ + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "conflictingPackages": [], + "dependencyGraph": { + "runtime-core": [], + "workflow-pack": [ + "runtime-core" + ] + }, + "resolutionOrder": [ + "runtime-core", + "workflow-pack" + ], + "requestedModules": [ + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "selectedModules": [ + "runtime-core", + "workflow-pack" + ], + "modules": [ + "runtime-core", + "workflow-pack" + ], + "managedFiles": [ + ".claude/skills/skills/SKILL.md", + ".agents/skills/skills/SKILL.md", + ".agents/skills/skills/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/skills-instincts.yaml", + ".claude/commands/update-documentation-files.md", + ".claude/commands/add-or-enhance-skill-package.md" + ], + "packageFiles": { + "runtime-core": [ + ".claude/skills/skills/SKILL.md", + ".agents/skills/skills/SKILL.md", + ".agents/skills/skills/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/skills-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/update-documentation-files.md", + ".claude/commands/add-or-enhance-skill-package.md" + ] + }, + "moduleFiles": { + "runtime-core": [ + ".claude/skills/skills/SKILL.md", + ".agents/skills/skills/SKILL.md", + ".agents/skills/skills/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/skills-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/update-documentation-files.md", + ".claude/commands/add-or-enhance-skill-package.md" + ] + }, + "files": [ + { + "moduleId": "runtime-core", + "path": ".claude/skills/skills/SKILL.md", + "description": "Repository-specific Claude Code skill generated from git history." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/skills/SKILL.md", + "description": "Codex-facing copy of the generated repository skill." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/skills/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/skills-instincts.yaml", + "description": "Continuous-learning instincts derived from repository patterns." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/update-documentation-files.md", + "description": "Workflow command scaffold for update-documentation-files." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/add-or-enhance-skill-package.md", + "description": "Workflow command scaffold for add-or-enhance-skill-package." + } + ], + "workflows": [ + { + "command": "update-documentation-files", + "path": ".claude/commands/update-documentation-files.md" + }, + { + "command": "add-or-enhance-skill-package", + "path": ".claude/commands/add-or-enhance-skill-package.md" + } + ], + "adapters": { + "claudeCode": { + "skillPath": ".claude/skills/skills/SKILL.md", + "identityPath": ".claude/identity.json", + "commandPaths": [ + ".claude/commands/update-documentation-files.md", + ".claude/commands/add-or-enhance-skill-package.md" + ] + }, + "codex": { + "configPath": ".codex/config.toml", + "agentsGuidePath": ".codex/AGENTS.md", + "skillPath": ".agents/skills/skills/SKILL.md" + } + } +} \ No newline at end of file diff --git a/.claude/homunculus/instincts/inherited/skills-instincts.yaml b/.claude/homunculus/instincts/inherited/skills-instincts.yaml new file mode 100644 index 0000000..21e4783 --- /dev/null +++ b/.claude/homunculus/instincts/inherited/skills-instincts.yaml @@ -0,0 +1,410 @@ +# Instincts generated from https://github.com/WardLu/skills +# Generated: 2026-08-01T06:52:27.555Z +# 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: skills-commit-conventional +trigger: "when writing a commit message" +confidence: 0.85 +domain: git +source: repo-analysis +source_repo: https://github.com/WardLu/skills +--- + +# Skills Commit Conventional + +## Action + +Use conventional commit format with prefixes: docs, feat + +## Evidence + +- 5 commits analyzed +- Detected conventional commit pattern +- Examples: feat: add Codex cross-provider session repair skill, docs: add bilingual install and cross-platform guidance + +--- +id: skills-commit-length +trigger: "when writing a commit message" +confidence: 0.6 +domain: git +source: repo-analysis +source_repo: https://github.com/WardLu/skills +--- + +# Skills Commit Length + +## Action + +Keep commit messages concise (~44 characters) + +## Evidence + +- Average commit message length: 44 chars +- Based on 5 commits + +--- +id: skills-naming-files +trigger: "when creating a new file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: https://github.com/WardLu/skills +--- + +# Skills Naming Files + +## Action + +Use PascalCase naming convention + +## Evidence + +- Analyzed file naming patterns in repository +- Dominant pattern: PascalCase + +--- +id: skills-import-relative +trigger: "when importing modules" +confidence: 0.75 +domain: code-style +source: repo-analysis +source_repo: https://github.com/WardLu/skills +--- + +# Skills Import Relative + +## Action + +Use relative imports for project files + +## Evidence + +- Import analysis shows relative import pattern +- Example: import { x } from '../lib/x' + +--- +id: skills-export-style +trigger: "when exporting from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: https://github.com/WardLu/skills +--- + +# Skills Export Style + +## Action + +Prefer named exports + +## Evidence + +- Export pattern analysis +- Dominant style: named + +--- +id: skills-workflow-update-documentation-files +trigger: "when doing update documentation files" +confidence: 0.65 +domain: workflow +source: repo-analysis +source_repo: https://github.com/WardLu/skills +--- + +# Skills Workflow Update Documentation Files + +## Action + +Follow the update-documentation-files workflow: +1. Edit or add content to README.md at the root or within a skill directory +2. Optionally update or add language-specific README files (e.g., README.zh-CN.md) +3. Update CHANGELOG.md and/or SKILL.md as needed +4. Commit changes with a docs-related message + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~3x per month +- Files: README.md, codex-cross-provider-session-repair/README.md, codex-cross-provider-session-repair/README.zh-CN.md + +--- +id: skills-workflow-add-or-enhance-skill-package +trigger: "when doing add or enhance skill package" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/WardLu/skills +--- + +# Skills Workflow Add Or Enhance Skill Package + +## Action + +Follow the add-or-enhance-skill-package workflow: +1. Create or update the skill directory with necessary files (README, SKILL.md, scripts, tests, etc.) +2. Add or update scripts (e.g., install.sh, package.py, repair.py) +3. Update or add tests in the tests/ subdirectory +4. Update documentation files within the skill (README.md, CHANGELOG.md, SKILL.md, etc.) +5. Commit all changes together + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: codex-cross-provider-session-repair/README.md, codex-cross-provider-session-repair/SKILL.md, codex-cross-provider-session-repair/CHANGELOG.md + +--- +id: skills-instinct-file-naming +trigger: "When creating or renaming a Python file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct File Naming + +## Action + +Use PascalCase for file names + +## Evidence + +- Pattern in namingConventions.files: PascalCase + +--- +id: skills-instinct-function-naming +trigger: "When defining a function in Python" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Function Naming + +## Action + +Use camelCase for function names + +## Evidence + +- Pattern in namingConventions.functions: camelCase + +--- +id: skills-instinct-class-naming +trigger: "When defining a class in Python" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Class Naming + +## Action + +Use PascalCase for class names + +## Evidence + +- Pattern in namingConventions.classes: PascalCase + +--- +id: skills-instinct-constant-naming +trigger: "When defining a constant in Python" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Constant Naming + +## Action + +Use SCREAMING_SNAKE_CASE for constant names + +## Evidence + +- Pattern in namingConventions.constants: SCREAMING_SNAKE_CASE + +--- +id: skills-instinct-relative-imports +trigger: "When importing modules within the package" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Relative Imports + +## Action + +Use relative import statements + +## Evidence + +- Pattern in importStyle: relative + +--- +id: skills-instinct-named-exports +trigger: "When exporting functions, classes, or variables from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Named Exports + +## Action + +Use named exports + +## Evidence + +- Pattern in exportStyle: named + +--- +id: skills-instinct-test-location +trigger: "When adding tests for a skill" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Test Location + +## Action + +Place test files in a tests/ subdirectory within the skill directory + +## Evidence + +- Pattern in architecture.folderStructure.testLocation: mixed +- Example: codex-cross-provider-session-repair/tests/test_repair.py + +--- +id: skills-instinct-test-naming +trigger: "When naming a test file" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Test Naming + +## Action + +Use the pattern test_.py (e.g., test_repair.py) + +## Evidence + +- Example: codex-cross-provider-session-repair/tests/test_repair.py + +--- +id: skills-instinct-conventional-commits +trigger: "When writing a commit message" +confidence: 0.9 +domain: git +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Conventional Commits + +## Action + +Use the conventional commit format: : (e.g., feat: add new skill) + +## Evidence + +- Pattern in commits.type: conventional +- Examples: 'feat: add Codex cross-provider session repair skill', 'docs: clarify collection scope in changelog' + +--- +id: skills-instinct-commit-prefixes +trigger: "When committing documentation or feature changes" +confidence: 0.9 +domain: git +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Commit Prefixes + +## Action + +Use 'docs:' for documentation and 'feat:' for new features in commit messages + +## Evidence + +- Pattern in commits.prefixes: ['docs', 'feat'] +- Examples: 'docs: clarify skill collection scope', 'feat: add Codex cross-provider session repair skill' + +--- +id: skills-instinct-commit-length +trigger: "When writing a commit message" +confidence: 0.7 +domain: git +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Commit Length + +## Action + +Keep the commit message concise, around 44 characters on average + +## Evidence + +- Pattern in commits.averageLength: 44 + +--- +id: skills-instinct-update-documentation +trigger: "When someone wants to improve, clarify, or add documentation for the repository or a skill" +confidence: 0.95 +domain: workflow +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Update Documentation + +## Action + +Edit or add content to README.md, optionally update language-specific README files, update CHANGELOG.md and/or SKILL.md as needed, and commit changes with a docs-related message + +## Evidence + +- Workflow: update-documentation-files +- Example commits: 'docs: add bilingual install and cross-platform guidance' + +--- +id: skills-instinct-add-or-enhance-skill +trigger: "When someone wants to introduce a new skill or make significant updates to an existing skill's implementation and documentation" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: WardLu/skills +--- + +# Skills Instinct Add Or Enhance Skill + +## Action + +Create or update the skill directory with necessary files (README, SKILL.md, scripts, tests, etc.), add or update scripts, update or add tests, update documentation files, and commit all changes together + +## Evidence + +- Workflow: add-or-enhance-skill-package +- Example commits: 'feat: add Codex cross-provider session repair skill' + diff --git a/.claude/identity.json b/.claude/identity.json new file mode 100644 index 0000000..1cfb231 --- /dev/null +++ b/.claude/identity.json @@ -0,0 +1,14 @@ +{ + "version": "2.0", + "technicalLevel": "technical", + "preferredStyle": { + "verbosity": "moderate", + "codeComments": true, + "explanations": true + }, + "domains": [ + "python" + ], + "suggestedBy": "ecc-tools-repo-analysis", + "createdAt": "2026-08-01T06:52:27.555Z" +} \ No newline at end of file diff --git a/.claude/skills/skills/SKILL.md b/.claude/skills/skills/SKILL.md new file mode 100644 index 0000000..8e3a797 --- /dev/null +++ b/.claude/skills/skills/SKILL.md @@ -0,0 +1,111 @@ +```markdown +# skills Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This repository demonstrates best practices for developing modular Python "skills" without a framework. It emphasizes clear documentation, consistent coding conventions, and structured workflows for adding, enhancing, and documenting skill packages. The patterns here are ideal for maintainable, collaborative Python codebases. + +## Coding Conventions + +- **File Naming:** + Use PascalCase for Python files and directories. + *Example:* + ``` + CodexCrossProviderSessionRepair/ + RepairSession.py + ``` + +- **Import Style:** + Use relative imports within skill packages. + *Example:* + ```python + from .RepairSession import RepairSession + ``` + +- **Export Style:** + Use named exports (explicitly define what is exported). + *Example:* + ```python + __all__ = ["RepairSession"] + ``` + +- **Commit Messages:** + Follow the [Conventional Commits](https://www.conventionalcommits.org/) style. + - Prefixes: `docs`, `feat` + - Example: + ``` + docs: update SKILL.md with new workflow + feat: add session repair logic + ``` + +## Workflows + +### update-documentation-files +**Trigger:** When you want to improve, clarify, or add documentation for the repository or a skill. +**Command:** `/update-docs` + +1. Edit or add content to `README.md` at the root or within a skill directory. +2. Optionally update or add language-specific README files (e.g., `README.zh-CN.md`). +3. Update `CHANGELOG.md` and/or `SKILL.md` as needed. +4. Commit changes with a `docs:`-prefixed message. + +*Example:* +```bash +# Edit documentation files +git add codex-cross-provider-session-repair/README.md +git commit -m "docs: clarify session repair steps" +``` + +--- + +### add-or-enhance-skill-package +**Trigger:** When you want to introduce a new skill or make significant updates to an existing skill's implementation and documentation. +**Command:** `/add-skill` + +1. Create or update the skill directory with necessary files (`README.md`, `SKILL.md`, scripts, tests, etc.). +2. Add or update scripts (e.g., `install.sh`, `package.py`, `repair.py`). +3. Update or add tests in the `tests/` subdirectory. +4. Update documentation files within the skill (`README.md`, `CHANGELOG.md`, `SKILL.md`, etc.). +5. Commit all changes together. + +*Example:* +```bash +# Add a new skill +mkdir codex-cross-provider-session-repair +touch codex-cross-provider-session-repair/README.md +touch codex-cross-provider-session-repair/SKILL.md +touch codex-cross-provider-session-repair/scripts/repair.py +mkdir codex-cross-provider-session-repair/tests +touch codex-cross-provider-session-repair/tests/test_repair.py + +git add codex-cross-provider-session-repair/ +git commit -m "feat: add codex cross-provider session repair skill" +``` + +## Testing Patterns + +- **Framework:** Not explicitly specified; use standard Python testing practices. +- **Test File Pattern:** Name test files as `*.test.*` or place them in a `tests/` subdirectory. +- **Example:** + ``` + codex-cross-provider-session-repair/tests/test_repair.py + ``` +- **Typical Test Structure:** + ```python + import unittest + from ..scripts.repair import repair_session + + class TestRepairSession(unittest.TestCase): + def test_repair(self): + self.assertTrue(repair_session()) + ``` + +## Commands + +| Command | Purpose | +|--------------|---------------------------------------------------------------| +| /update-docs | Update documentation files (README, SKILL.md, CHANGELOG, etc) | +| /add-skill | Add or enhance a skill package with code, tests, and docs | +``` diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 0000000..e597551 --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,27 @@ +# ECC for Codex CLI + +This supplements the root `AGENTS.md` with a repo-local ECC baseline. + +## Repo Skill + +- Repo-generated Codex skill: `.agents/skills/skills/SKILL.md` +- Claude-facing companion skill: `.claude/skills/skills/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/update-documentation-files.md` +- `.claude/commands/add-or-enhance-skill-package.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