diff --git a/.agents/skills/QwenVoice/SKILL.md b/.agents/skills/QwenVoice/SKILL.md new file mode 100644 index 0000000..93a9b66 --- /dev/null +++ b/.agents/skills/QwenVoice/SKILL.md @@ -0,0 +1,122 @@ +```markdown +# QwenVoice Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill teaches the core development patterns and workflows for the QwenVoice TypeScript codebase. It covers coding conventions, file organization, import/export styles, and the main project maintenance workflows, including how to update operating guides and enforcement scripts. The guide is intended for contributors seeking to maintain consistency and follow best practices within the QwenVoice repository. + +## Coding Conventions + +### File Naming + +- Use **camelCase** for file names. + - Example: `audioProcessor.ts`, `voiceSynthesizer.test.ts` + +### Import Style + +- Use **relative imports** for internal modules. + - Example: + ```typescript + import { processAudio } from './audioProcessor'; + ``` + +### Export Style + +- Use **named exports** for all modules. + - Example: + ```typescript + // audioProcessor.ts + export function processAudio(input: Buffer): Buffer { ... } + ``` + +### Commit Patterns + +- Commit messages are **freeform** (no enforced prefix). +- Average commit message length: ~53 characters. + +## Workflows + +### Operating Guide Replacement & Update + +**Trigger:** When the main project operating guide is replaced or renamed (e.g., `AGENTS.md` → `CLAUDE.md`). + +**Command:** `/replace-operating-guide` + +**Step-by-step:** + +1. **Create or expand the new operating guide file** + - Example: Add or update `CLAUDE.md` with the latest content, merging or rewriting as needed. +2. **Delete or deprecate the old guide** + - Example: Remove `AGENTS.md` from the repository. +3. **Update all documentation references** + - Search for all references to the old guide in documentation files (e.g., `docs/README.md`, `docs/qwen_tone.md`, etc.) and update them to point to the new guide. + - Example: + ```diff + - See AGENTS.md for the operating guide. + + See CLAUDE.md for the operating guide. + ``` +4. **Update enforcement scripts** + - Modify scripts like `scripts/check_project_inputs.sh` to allow or disallow references to the new/old guide as appropriate. + - Example: + ```bash + # In scripts/check_project_inputs.sh + PROHIBITED_REFERENCE_PATTERNS=("AGENTS.md") + # Update to: + PROHIBITED_REFERENCE_PATTERNS=("CLAUDE.md") + ``` + +**Files Involved:** +- `CLAUDE.md` +- `AGENTS.md` +- `docs/README.md` +- `docs/qwen_tone.md` +- `docs/reference/current-state.md` +- `docs/reference/backend-freeze-gate.md` +- `docs/reference/frontend-backend-contract.md` +- `scripts/check_project_inputs.sh` + +--- + +### Enforcement Script Reference Update + +**Trigger:** When the set of allowed or prohibited references in the codebase changes (e.g., after adding or renaming a guide). + +**Command:** `/update-reference-enforcement` + +**Step-by-step:** + +1. **Modify enforcement scripts** + - Edit `scripts/check_project_inputs.sh` to update `PROHIBITED_REFERENCE_PATTERNS` or similar logic to reflect the new set of allowed/banned references. + - Example: + ```bash + # Allow references to CLAUDE.md, ban AGENTS.md + PROHIBITED_REFERENCE_PATTERNS=("AGENTS.md") + ``` +2. **Test enforcement** + - Run the script and verify that the intended references are correctly allowed or banned. + - Example: + ```bash + bash scripts/check_project_inputs.sh + ``` + +**Files Involved:** +- `scripts/check_project_inputs.sh` + +--- + +## Testing Patterns + +- **Test files** follow the pattern: `*.test.*` + - Example: `voiceSynthesizer.test.ts` +- **Testing framework:** Not explicitly detected; check test files for framework usage. +- **Test organization:** Tests are colocated with source files or in dedicated test directories. + +## Commands + +| Command | Purpose | +|-----------------------------|----------------------------------------------------------------| +| /replace-operating-guide | Transition to a new operating guide and update all references. | +| /update-reference-enforcement | Update enforcement scripts for allowed/prohibited references. | +``` \ No newline at end of file diff --git a/.agents/skills/QwenVoice/agents/openai.yaml b/.agents/skills/QwenVoice/agents/openai.yaml new file mode 100644 index 0000000..89514d1 --- /dev/null +++ b/.agents/skills/QwenVoice/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "QwenVoice" + short_description: "Repo-specific patterns and workflows for QwenVoice" + default_prompt: "Use the QwenVoice 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/enforcement-script-reference-update.md b/.claude/commands/enforcement-script-reference-update.md new file mode 100644 index 0000000..57ee971 --- /dev/null +++ b/.claude/commands/enforcement-script-reference-update.md @@ -0,0 +1,34 @@ +--- +name: enforcement-script-reference-update +description: Workflow command scaffold for enforcement-script-reference-update in QwenVoice. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /enforcement-script-reference-update + +Use this workflow when working on **enforcement-script-reference-update** in `QwenVoice`. + +## Goal + +Updating enforcement scripts to allow or ban references to specific files or patterns in the project. + +## Common Files + +- `scripts/check_project_inputs.sh` + +## 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 + +- Modify scripts/check_project_inputs.sh to update PROHIBITED_REFERENCE_PATTERNS or similar logic. +- Test that the new references are correctly allowed or banned as intended. + +## 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/operating-guide-replacement-update.md b/.claude/commands/operating-guide-replacement-update.md new file mode 100644 index 0000000..8a01b4f --- /dev/null +++ b/.claude/commands/operating-guide-replacement-update.md @@ -0,0 +1,41 @@ +--- +name: operating-guide-replacement-update +description: Workflow command scaffold for operating-guide-replacement-update in QwenVoice. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /operating-guide-replacement-update + +Use this workflow when working on **operating-guide-replacement-update** in `QwenVoice`. + +## Goal + +Transitioning the primary operating guide from one file to another, updating all references and related enforcement scripts. + +## Common Files + +- `CLAUDE.md` +- `AGENTS.md` +- `docs/README.md` +- `docs/qwen_tone.md` +- `docs/reference/current-state.md` +- `docs/reference/backend-freeze-gate.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 + +- Create or expand the new operating guide file (e.g., CLAUDE.md) with updated or merged content. +- Delete or deprecate the old operating guide file (e.g., AGENTS.md). +- Update all documentation files that reference the old guide to point to the new guide. +- Update enforcement scripts (e.g., scripts/check_project_inputs.sh) to allow or disallow references to the new/old guide as appropriate. + +## 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..7ec3a38 --- /dev/null +++ b/.claude/ecc-tools.json @@ -0,0 +1,217 @@ +{ + "version": "1.3", + "schemaVersion": "1.0", + "generatedBy": "ecc-tools", + "generatedAt": "2026-05-01T14:30:37.831Z", + "repo": "https://github.com/PowerBeef/QwenVoice", + "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/QwenVoice/SKILL.md", + ".agents/skills/QwenVoice/SKILL.md", + ".agents/skills/QwenVoice/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/QwenVoice-instincts.yaml", + ".claude/commands/operating-guide-replacement-update.md", + ".claude/commands/enforcement-script-reference-update.md" + ], + "packageFiles": { + "runtime-core": [ + ".claude/skills/QwenVoice/SKILL.md", + ".agents/skills/QwenVoice/SKILL.md", + ".agents/skills/QwenVoice/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/QwenVoice-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/operating-guide-replacement-update.md", + ".claude/commands/enforcement-script-reference-update.md" + ] + }, + "moduleFiles": { + "runtime-core": [ + ".claude/skills/QwenVoice/SKILL.md", + ".agents/skills/QwenVoice/SKILL.md", + ".agents/skills/QwenVoice/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/QwenVoice-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/operating-guide-replacement-update.md", + ".claude/commands/enforcement-script-reference-update.md" + ] + }, + "files": [ + { + "moduleId": "runtime-core", + "path": ".claude/skills/QwenVoice/SKILL.md", + "description": "Repository-specific Claude Code skill generated from git history." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/QwenVoice/SKILL.md", + "description": "Codex-facing copy of the generated repository skill." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/QwenVoice/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/QwenVoice-instincts.yaml", + "description": "Continuous-learning instincts derived from repository patterns." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/operating-guide-replacement-update.md", + "description": "Workflow command scaffold for operating-guide-replacement-update." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/enforcement-script-reference-update.md", + "description": "Workflow command scaffold for enforcement-script-reference-update." + } + ], + "workflows": [ + { + "command": "operating-guide-replacement-update", + "path": ".claude/commands/operating-guide-replacement-update.md" + }, + { + "command": "enforcement-script-reference-update", + "path": ".claude/commands/enforcement-script-reference-update.md" + } + ], + "adapters": { + "claudeCode": { + "skillPath": ".claude/skills/QwenVoice/SKILL.md", + "identityPath": ".claude/identity.json", + "commandPaths": [ + ".claude/commands/operating-guide-replacement-update.md", + ".claude/commands/enforcement-script-reference-update.md" + ] + }, + "codex": { + "configPath": ".codex/config.toml", + "agentsGuidePath": ".codex/AGENTS.md", + "skillPath": ".agents/skills/QwenVoice/SKILL.md" + } + } +} \ No newline at end of file diff --git a/.claude/homunculus/instincts/inherited/QwenVoice-instincts.yaml b/.claude/homunculus/instincts/inherited/QwenVoice-instincts.yaml new file mode 100644 index 0000000..ead78b2 --- /dev/null +++ b/.claude/homunculus/instincts/inherited/QwenVoice-instincts.yaml @@ -0,0 +1,350 @@ +# Instincts generated from https://github.com/PowerBeef/QwenVoice +# Generated: 2026-05-01T14:31:02.466Z +# 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: QwenVoice-commit-length +trigger: "when writing a commit message" +confidence: 0.6 +domain: git +source: repo-analysis +source_repo: https://github.com/PowerBeef/QwenVoice +--- + +# QwenVoice Commit Length + +## Action + +Write moderate-length commit messages (~53 characters) + +## Evidence + +- Average commit message length: 53 chars +- Based on 3 commits + +--- +id: QwenVoice-naming-files +trigger: "when creating a new file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: https://github.com/PowerBeef/QwenVoice +--- + +# QwenVoice Naming Files + +## Action + +Use camelCase naming convention + +## Evidence + +- Analyzed file naming patterns in repository +- Dominant pattern: camelCase + +--- +id: QwenVoice-import-relative +trigger: "when importing modules" +confidence: 0.75 +domain: code-style +source: repo-analysis +source_repo: https://github.com/PowerBeef/QwenVoice +--- + +# QwenVoice Import Relative + +## Action + +Use relative imports for project files + +## Evidence + +- Import analysis shows relative import pattern +- Example: import { x } from '../lib/x' + +--- +id: QwenVoice-export-style +trigger: "when exporting from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: https://github.com/PowerBeef/QwenVoice +--- + +# QwenVoice Export Style + +## Action + +Prefer named exports + +## Evidence + +- Export pattern analysis +- Dominant style: named + +--- +id: QwenVoice-test-separate +trigger: "when writing tests" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: https://github.com/PowerBeef/QwenVoice +--- + +# QwenVoice Test Separate + +## Action + +Place tests in the tests/ or __tests__/ directory, mirroring src structure + +## Evidence + +- Separate test directory pattern detected +- Tests live in dedicated test folders + +--- +id: QwenVoice-workflow-operating-guide-replacement-update +trigger: "when doing operating guide replacement update" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/PowerBeef/QwenVoice +--- + +# QwenVoice Workflow Operating Guide Replacement Update + +## Action + +Follow the operating-guide-replacement-update workflow: +1. Create or expand the new operating guide file (e.g., CLAUDE.md) with updated or merged content. +2. Delete or deprecate the old operating guide file (e.g., AGENTS.md). +3. Update all documentation files that reference the old guide to point to the new guide. +4. Update enforcement scripts (e.g., scripts/check_project_inputs.sh) to allow or disallow references to the new/old guide as appropriate. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: CLAUDE.md, AGENTS.md, docs/README.md + +--- +id: QwenVoice-workflow-enforcement-script-reference-update +trigger: "when doing enforcement script reference update" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/PowerBeef/QwenVoice +--- + +# QwenVoice Workflow Enforcement Script Reference Update + +## Action + +Follow the enforcement-script-reference-update workflow: +1. Modify scripts/check_project_inputs.sh to update PROHIBITED_REFERENCE_PATTERNS or similar logic. +2. Test that the new references are correctly allowed or banned as intended. + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: scripts/check_project_inputs.sh + +--- +id: qwenvoice-instinct-camelcase-files +trigger: "When creating or renaming a file in the codebase" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Camelcase Files + +## Action + +Name the file using camelCase convention + +## Evidence + +- Pattern in codeStyle.namingConventions.files + +--- +id: qwenvoice-instinct-camelcase-functions +trigger: "When defining a function" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Camelcase Functions + +## Action + +Name the function using camelCase convention + +## Evidence + +- Pattern in codeStyle.namingConventions.functions + +--- +id: qwenvoice-instinct-pascalcase-classes +trigger: "When defining a class" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Pascalcase Classes + +## Action + +Name the class using PascalCase convention + +## Evidence + +- Pattern in codeStyle.namingConventions.classes + +--- +id: qwenvoice-instinct-screaming-constants +trigger: "When declaring a constant" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Screaming Constants + +## Action + +Name the constant using SCREAMING_SNAKE_CASE convention + +## Evidence + +- Pattern in codeStyle.namingConventions.constants + +--- +id: qwenvoice-instinct-relative-imports +trigger: "When importing modules within the project" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Relative Imports + +## Action + +Use relative import paths + +## Evidence + +- Pattern in codeStyle.importStyle + +--- +id: qwenvoice-instinct-named-exports +trigger: "When exporting modules or functions" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Named Exports + +## Action + +Use named exports instead of default exports + +## Evidence + +- Pattern in codeStyle.exportStyle + +--- +id: qwenvoice-instinct-test-separate-folder +trigger: "When adding or organizing tests" +confidence: 0.7 +domain: testing +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Test Separate Folder + +## Action + +Place test files in a separate test folder, not mixed with source files + +## Evidence + +- Pattern in architecture.folderStructure.testLocation + +--- +id: qwenvoice-instinct-commit-freeform +trigger: "When writing a git commit message" +confidence: 0.7 +domain: git +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Commit Freeform + +## Action + +Use a concise, freeform message without a strict prefix, typically under 60 characters + +## Evidence + +- Pattern in commits.type +- Average commit length +- Examples: 'Add CLAUDE.md operating guide' + +--- +id: qwenvoice-instinct-operating-guide-replacement +trigger: "When the main project operating guide is replaced or renamed (e.g., AGENTS.md → CLAUDE.md)" +confidence: 0.95 +domain: workflow +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Operating Guide Replacement + +## Action + +Create or expand the new guide, deprecate the old guide, update all references in documentation, and update enforcement scripts accordingly + +## Evidence + +- Workflow: operating-guide-replacement-update +- Commits: 'Add CLAUDE.md operating guide', 'Replace AGENTS.md with CLAUDE.md as the primary operating guide' +- Files: CLAUDE.md, AGENTS.md, docs/README.md, scripts/check_project_inputs.sh + +--- +id: qwenvoice-instinct-enforcement-script-update +trigger: "When the set of allowed or prohibited references in the codebase changes" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: PowerBeef/QwenVoice +--- + +# Qwenvoice Instinct Enforcement Script Update + +## Action + +Update scripts/check_project_inputs.sh to reflect the new reference rules and test enforcement + +## Evidence + +- Workflow: enforcement-script-reference-update +- Commits: 'Allow CLAUDE.md and Claude Code references in project-inputs check' +- File: scripts/check_project_inputs.sh + diff --git a/.claude/identity.json b/.claude/identity.json new file mode 100644 index 0000000..311d60d --- /dev/null +++ b/.claude/identity.json @@ -0,0 +1,14 @@ +{ + "version": "2.0", + "technicalLevel": "technical", + "preferredStyle": { + "verbosity": "moderate", + "codeComments": true, + "explanations": true + }, + "domains": [ + "typescript" + ], + "suggestedBy": "ecc-tools-repo-analysis", + "createdAt": "2026-05-01T14:31:02.466Z" +} \ No newline at end of file diff --git a/.claude/skills/QwenVoice/SKILL.md b/.claude/skills/QwenVoice/SKILL.md new file mode 100644 index 0000000..93a9b66 --- /dev/null +++ b/.claude/skills/QwenVoice/SKILL.md @@ -0,0 +1,122 @@ +```markdown +# QwenVoice Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill teaches the core development patterns and workflows for the QwenVoice TypeScript codebase. It covers coding conventions, file organization, import/export styles, and the main project maintenance workflows, including how to update operating guides and enforcement scripts. The guide is intended for contributors seeking to maintain consistency and follow best practices within the QwenVoice repository. + +## Coding Conventions + +### File Naming + +- Use **camelCase** for file names. + - Example: `audioProcessor.ts`, `voiceSynthesizer.test.ts` + +### Import Style + +- Use **relative imports** for internal modules. + - Example: + ```typescript + import { processAudio } from './audioProcessor'; + ``` + +### Export Style + +- Use **named exports** for all modules. + - Example: + ```typescript + // audioProcessor.ts + export function processAudio(input: Buffer): Buffer { ... } + ``` + +### Commit Patterns + +- Commit messages are **freeform** (no enforced prefix). +- Average commit message length: ~53 characters. + +## Workflows + +### Operating Guide Replacement & Update + +**Trigger:** When the main project operating guide is replaced or renamed (e.g., `AGENTS.md` → `CLAUDE.md`). + +**Command:** `/replace-operating-guide` + +**Step-by-step:** + +1. **Create or expand the new operating guide file** + - Example: Add or update `CLAUDE.md` with the latest content, merging or rewriting as needed. +2. **Delete or deprecate the old guide** + - Example: Remove `AGENTS.md` from the repository. +3. **Update all documentation references** + - Search for all references to the old guide in documentation files (e.g., `docs/README.md`, `docs/qwen_tone.md`, etc.) and update them to point to the new guide. + - Example: + ```diff + - See AGENTS.md for the operating guide. + + See CLAUDE.md for the operating guide. + ``` +4. **Update enforcement scripts** + - Modify scripts like `scripts/check_project_inputs.sh` to allow or disallow references to the new/old guide as appropriate. + - Example: + ```bash + # In scripts/check_project_inputs.sh + PROHIBITED_REFERENCE_PATTERNS=("AGENTS.md") + # Update to: + PROHIBITED_REFERENCE_PATTERNS=("CLAUDE.md") + ``` + +**Files Involved:** +- `CLAUDE.md` +- `AGENTS.md` +- `docs/README.md` +- `docs/qwen_tone.md` +- `docs/reference/current-state.md` +- `docs/reference/backend-freeze-gate.md` +- `docs/reference/frontend-backend-contract.md` +- `scripts/check_project_inputs.sh` + +--- + +### Enforcement Script Reference Update + +**Trigger:** When the set of allowed or prohibited references in the codebase changes (e.g., after adding or renaming a guide). + +**Command:** `/update-reference-enforcement` + +**Step-by-step:** + +1. **Modify enforcement scripts** + - Edit `scripts/check_project_inputs.sh` to update `PROHIBITED_REFERENCE_PATTERNS` or similar logic to reflect the new set of allowed/banned references. + - Example: + ```bash + # Allow references to CLAUDE.md, ban AGENTS.md + PROHIBITED_REFERENCE_PATTERNS=("AGENTS.md") + ``` +2. **Test enforcement** + - Run the script and verify that the intended references are correctly allowed or banned. + - Example: + ```bash + bash scripts/check_project_inputs.sh + ``` + +**Files Involved:** +- `scripts/check_project_inputs.sh` + +--- + +## Testing Patterns + +- **Test files** follow the pattern: `*.test.*` + - Example: `voiceSynthesizer.test.ts` +- **Testing framework:** Not explicitly detected; check test files for framework usage. +- **Test organization:** Tests are colocated with source files or in dedicated test directories. + +## Commands + +| Command | Purpose | +|-----------------------------|----------------------------------------------------------------| +| /replace-operating-guide | Transition to a new operating guide and update all references. | +| /update-reference-enforcement | Update enforcement scripts for allowed/prohibited references. | +``` \ No newline at end of file diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 0000000..379160f --- /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/QwenVoice/SKILL.md` +- Claude-facing companion skill: `.claude/skills/QwenVoice/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/operating-guide-replacement-update.md` +- `.claude/commands/enforcement-script-reference-update.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