Compare commits

..

16 Commits

Author SHA1 Message Date
ecc-tools[bot]
cdbaf9feff feat: add everything-claude-code ECC bundle (.claude/commands/add-or-update-skill.md) 2026-04-01 23:06:45 +00:00
ecc-tools[bot]
8f2170f9cf feat: add everything-claude-code ECC bundle (.claude/commands/refactoring.md) 2026-04-01 23:06:44 +00:00
ecc-tools[bot]
7ac28b45eb feat: add everything-claude-code ECC bundle (.claude/commands/feature-development.md) 2026-04-01 23:06:43 +00:00
ecc-tools[bot]
d7bffc3f5a feat: add everything-claude-code ECC bundle (.claude/enterprise/controls.md) 2026-04-01 23:06:42 +00:00
ecc-tools[bot]
e9aeeb13d7 feat: add everything-claude-code ECC bundle (.claude/team/everything-claude-code-team-config.json) 2026-04-01 23:06:42 +00:00
ecc-tools[bot]
d0103898bb feat: add everything-claude-code ECC bundle (.claude/research/everything-claude-code-research-playbook.md) 2026-04-01 23:06:41 +00:00
ecc-tools[bot]
4356273cfa feat: add everything-claude-code ECC bundle (.claude/rules/everything-claude-code-guardrails.md) 2026-04-01 23:06:40 +00:00
ecc-tools[bot]
b5907ccfbd feat: add everything-claude-code ECC bundle (.codex/agents/docs-researcher.toml) 2026-04-01 23:06:39 +00:00
ecc-tools[bot]
7e0d803bed feat: add everything-claude-code ECC bundle (.codex/agents/reviewer.toml) 2026-04-01 23:06:38 +00:00
ecc-tools[bot]
4b6de88b90 feat: add everything-claude-code ECC bundle (.codex/agents/explorer.toml) 2026-04-01 23:06:37 +00:00
ecc-tools[bot]
0f2089e2ad feat: add everything-claude-code ECC bundle (.claude/identity.json) 2026-04-01 23:06:36 +00:00
ecc-tools[bot]
1e1edd1b9e feat: add everything-claude-code ECC bundle (.agents/skills/everything-claude-code/agents/openai.yaml) 2026-04-01 23:06:35 +00:00
ecc-tools[bot]
a68feb7ac7 feat: add everything-claude-code ECC bundle (.agents/skills/everything-claude-code/SKILL.md) 2026-04-01 23:06:34 +00:00
ecc-tools[bot]
eb564ee4b6 feat: add everything-claude-code ECC bundle (.claude/skills/everything-claude-code/SKILL.md) 2026-04-01 23:06:33 +00:00
ecc-tools[bot]
ab19584689 feat: add everything-claude-code ECC bundle (.claude/ecc-tools.json) 2026-04-01 23:06:33 +00:00
Affaan Mustafa
dba5ae779b fix: harden install and codex sync portability 2026-04-01 16:04:56 -07:00
14 changed files with 432 additions and 291 deletions

View File

@@ -5,159 +5,173 @@
## Overview
This skill teaches the core development patterns, coding conventions, and common workflows used in the `everything-claude-code` repository. The codebase is primarily JavaScript, with no major framework, and is organized around modular skills, agent definitions, command workflows, and extensible install targets. The repository emphasizes clear documentation, conventional commits, and maintainable architecture for agent and workflow development.
This skill documents the core development patterns, coding conventions, and agentic workflows used in the `everything-claude-code` (ECC) repository. The project is written in JavaScript (no framework detected) and implements modular, agent-driven automation and installable skills. This guide covers how to contribute new skills, commands, install targets, agent definitions, and more, following the repository's conventions and workflows.
## Coding Conventions
- **File Naming:**
Use `camelCase` for JavaScript files and directories.
*Example:*
```
scripts/lib/installTargets.js
agentPrompts.md
```
ECC follows consistent JavaScript coding and repository organization conventions:
- **Import Style:**
Use **relative imports** for modules.
*Example:*
### File Naming
- Use **camelCase** for JavaScript files and modules.
- Example: `myModule.js`, `installTarget.js`
### Import Style
- Use **relative imports** for internal modules.
```js
const installTarget = require('../lib/installTargets');
// Good
const utils = require('./utils');
import { doThing } from '../lib/doThing.js';
```
- **Export Style:**
Both CommonJS (`module.exports`) and ES module (`export`) styles are present.
*Example (CommonJS):*
### Export Style
- Both **CommonJS** and **ES module** exports are used, depending on context.
```js
module.exports = function mySkill() { ... };
```
*Example (ES Module):*
```js
export function mySkill() { ... }
// CommonJS
module.exports = function doSomething() { ... };
// ES Module
export function doSomethingElse() { ... }
```
- **Commit Messages:**
Use [Conventional Commits](https://www.conventionalcommits.org/).
Prefixes: `fix`, `feat`, `docs`, `chore`
*Example:*
```
feat: add Gemini install target support
fix: correct agent prompt registration logic
```
### Commit Messages
- **Documentation:**
Each skill or agent should have a `SKILL.md` or `.md` documentation file explaining its purpose and usage.
- Prefix with `fix:`, `feat:`, `docs:`, or `chore:`
- Keep messages concise (average ~56 characters)
```
feat: add support for new install target
fix: resolve agent prompt parsing bug
```
## Workflows
### Add New Skill
**Trigger:** When introducing a new skill for agents or workflows
### Add or Update a Skill
**Trigger:** When introducing or updating a skill for agentic workflows
**Command:** `/add-skill`
1. Create a new `SKILL.md` file under `skills/`, `.agents/skills/`, or `.claude/skills/`.
2. Document the skill's purpose, usage, and configuration.
3. Optionally update manifests or documentation if the skill is significant.
1. Create or update a `SKILL.md` file under `skills/{skill-name}/` or `.agents/skills/{skill-name}/`.
2. Optionally update `AGENTS.md`, `README.md`, and localized docs (e.g., `README.zh-CN.md`).
3. Update `manifests/install-modules.json` and/or `install-components.json` if the skill is installable.
4. Optionally add or update related agent markdown files.
5. Optionally update tests or scripts if the skill introduces new hooks or behaviors.
*Example:*
```
skills/myNewSkill/SKILL.md
**Example:**
```shell
mkdir -p skills/myNewSkill
touch skills/myNewSkill/SKILL.md
# Edit SKILL.md with documentation
```
---
### Add New Agent or Agent Prompt
**Trigger:** When introducing a new agent persona or capability
**Command:** `/add-agent`
### Add or Update a Command Workflow
1. Create a new agent definition (e.g., `agents/myAgent.md` or `.opencode/prompts/agents/myAgent.txt`).
2. Register the agent in the relevant configuration file (e.g., `.opencode/opencode.json`).
3. Update `AGENTS.md` or related documentation.
*Example:*
```
agents/supportAgent.md
```
---
### Add or Update Command Workflow
**Trigger:** When introducing or improving a workflow command
**Trigger:** When adding or updating a repeatable workflow command
**Command:** `/add-command`
1. Create or update a command file under `commands/` (e.g., `commands/review.md`).
2. Optionally update related documentation or scripts.
3. Address review feedback and refine command logic.
1. Create or update a markdown file in `commands/` (e.g., `prp-*.md`, `gan-*.md`, `santa-loop.md`).
2. Document workflow phases, usage, and outputs in the file.
3. Optionally update related skills or agent definitions.
4. Optionally add shell scripts or orchestrators if automation is needed.
5. Optionally update `AGENTS.md` or `README.md` to reference the new command.
**Example:**
```shell
touch commands/prp-myworkflow.md
# Document the workflow steps in markdown
```
---
### Add Install Target or Adapter
**Trigger:** When supporting a new platform or integration
### Add or Update an Install Target
**Trigger:** When supporting a new IDE/platform or updating install logic
**Command:** `/add-install-target`
1. Add new install scripts and documentation under a dot-directory (e.g., `.gemini/`, `.codebuddy/`).
2. Update `manifests/install-modules.json` and relevant schema files.
3. Implement or update `scripts/lib/install-targets/*.js` for the new target.
4. Add or update tests for the install target.
1. Add or update install scripts (`install.sh`, `install.js`, `uninstall.sh`, `uninstall.js`) in a new or existing directory (e.g., `.codebuddy/`).
2. Update `manifests/install-modules.json` and `schemas/ecc-install-config.schema.json`.
3. Update `scripts/lib/install-manifests.js` and `scripts/lib/install-targets/{target}.js`.
4. Add or update tests for install targets.
5. Optionally update `README.md` or `AGENTS.md`.
*Example:*
```
.gemini/install.sh
scripts/lib/install-targets/gemini.js
tests/lib/install-targets.test.js
**Example:**
```shell
mkdir -p .codebuddy
touch .codebuddy/install.sh
# Implement install logic
```
---
### Refactor or Collapse Commands to Skills
**Trigger:** When modernizing command logic under the skills architecture
**Command:** `/refactor-to-skill`
### Update Hooks and Hook Tests
1. Update or remove `commands/*.md` files.
2. Add or update `skills/*/SKILL.md` files.
3. Update documentation (`README.md`, `AGENTS.md`, `WORKING-CONTEXT.md`, etc.).
4. Update manifests if required.
**Trigger:** When refactoring, fixing, or extending system hooks
**Command:** `/update-hook`
1. Edit `hooks/hooks.json` to change configuration or add/remove hooks.
2. Edit or add `scripts/hooks/*.js` to implement hook logic.
3. Edit or add `tests/hooks/*.test.js` to cover new or changed behaviors.
4. Optionally update related scripts or documentation.
**Example:**
```json
// hooks/hooks.json
{
"pre-commit": ["format", "typecheck"]
}
```
---
### Documentation and Guidance Update
**Trigger:** When clarifying, updating, or adding documentation
**Command:** `/update-docs`
### Dependency Bump via Dependabot
1. Edit or create documentation files (`README.md`, `WORKING-CONTEXT.md`, `docs/*.md`, etc.).
2. Sync or update guidance in multiple language versions if needed.
3. Optionally update related configuration or manifest files.
**Trigger:** When updating dependencies for security or features
**Command:** `/bump-dependency`
1. Update dependency version in `package.json`, `yarn.lock`, or workflow YAML files.
2. Commit with a standardized message (often by dependabot).
3. Optionally update related documentation or changelogs.
**Example:**
```json
// package.json
"dependencies": {
"some-lib": "^2.0.0"
}
```
---
### CI/CD Workflow Update
**Trigger:** When improving or fixing CI/CD processes
**Command:** `/update-ci`
### Add or Update Agent Definition
1. Edit `.github/workflows/*.yml` files.
2. Update lockfiles (`package-lock.json`, `yarn.lock`) or validation scripts.
3. Update or add test files for CI/CD logic.
**Trigger:** When adding or modifying agent definitions/prompts
**Command:** `/add-agent`
---
1. Add or update agent markdown files (`agents/*.md`).
2. Add or update prompt files (`.opencode/prompts/agents/*.txt`).
3. Update `.opencode/opencode.json` to register new agents.
4. Update `AGENTS.md` to document new agents.
5. Optionally update related skills or orchestrators.
**Example:**
```shell
touch agents/myAgent.md
touch .opencode/prompts/agents/myAgent.txt
```
## Testing Patterns
- **Test Files:**
Test files follow the pattern `*.test.js`.
- **Framework:**
No specific testing framework detected; structure your tests in standard Node.js or your preferred test runner.
*Example:*
```
tests/lib/install-targets.test.js
```
- **Test Example:**
- Test files follow the pattern `*.test.js`.
- Testing framework is **unknown** (not detected), but test files are placed alongside code or in `tests/` directories.
- Example test file:
```js
// install-targets.test.js
const installTarget = require('../../scripts/lib/install-targets/gemini');
test('should install Gemini target', () => {
expect(installTarget()).toBe(true);
// tests/hooks/formatHook.test.js
const formatHook = require('../../scripts/hooks/formatHook');
test('should format code correctly', () => {
// test implementation
});
```
@@ -165,11 +179,10 @@ tests/lib/install-targets.test.js
| Command | Purpose |
|--------------------|----------------------------------------------------------------|
| /add-skill | Add a new skill module and document it |
| /add-agent | Add a new agent definition or prompt |
| /add-command | Add or update a command workflow |
| /add-install-target| Add a new install target or adapter |
| /refactor-to-skill | Refactor commands into skill-based modules |
| /update-docs | Update documentation or guidance files |
| /update-ci | Update CI/CD workflows, lockfiles, or validation scripts |
| /add-skill | Add or update a skill and its documentation |
| /add-command | Add or update a workflow command |
| /add-install-target| Add or update an install target (IDE/platform/environment) |
| /update-hook | Refactor, fix, or extend system hooks and their tests |
| /bump-dependency | Update dependency versions in package or workflow files |
| /add-agent | Add or update agent definitions and prompts |
```

View File

@@ -1,37 +0,0 @@
---
name: add-new-skill
description: Workflow command scaffold for add-new-skill in everything-claude-code.
allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"]
---
# /add-new-skill
Use this workflow when working on **add-new-skill** in `everything-claude-code`.
## Goal
Adds a new skill to the codebase, typically as a new agent capability or workflow module.
## Common Files
- `skills/*/SKILL.md`
- `.agents/skills/*/SKILL.md`
- `.claude/skills/*/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
- Create a new SKILL.md file under skills/ or .agents/skills/ or .claude/skills/
- Document the skill's purpose, usage, and configuration.
- Optionally update manifests or documentation if the skill is significant.
## Notes
- Treat this as a scaffold, not a hard-coded script.
- Update the command if the workflow evolves materially.

View File

@@ -0,0 +1,42 @@
---
name: add-or-update-skill
description: Workflow command scaffold for add-or-update-skill in everything-claude-code.
allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"]
---
# /add-or-update-skill
Use this workflow when working on **add-or-update-skill** in `everything-claude-code`.
## Goal
Adds a new skill or updates an existing skill for an agentic workflow, including documentation and sometimes related manifests.
## Common Files
- `skills/*/SKILL.md`
- `.agents/skills/*/SKILL.md`
- `AGENTS.md`
- `README.md`
- `README.zh-CN.md`
- `docs/zh-CN/AGENTS.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 update a SKILL.md file under skills/{skill-name}/ or .agents/skills/{skill-name}/
- Optionally update AGENTS.md, README.md, and localized docs
- Update manifests/install-modules.json and/or install-components.json if the skill is part of installable modules
- Optionally add or update related agent markdown files
- Optionally update tests or scripts if the skill introduces new hooks or behaviors
## Notes
- Treat this as a scaffold, not a hard-coded script.
- Update the command if the workflow evolves materially.

View File

@@ -2,7 +2,7 @@
"version": "1.3",
"schemaVersion": "1.0",
"generatedBy": "ecc-tools",
"generatedAt": "2026-04-01T22:51:43.152Z",
"generatedAt": "2026-04-01T23:05:46.781Z",
"repo": "https://github.com/affaan-m/everything-claude-code",
"profiles": {
"requested": "full",
@@ -150,7 +150,7 @@
".claude/enterprise/controls.md",
".claude/commands/feature-development.md",
".claude/commands/refactoring.md",
".claude/commands/add-new-skill.md"
".claude/commands/add-or-update-skill.md"
],
"packageFiles": {
"runtime-core": [
@@ -180,7 +180,7 @@
"workflow-pack": [
".claude/commands/feature-development.md",
".claude/commands/refactoring.md",
".claude/commands/add-new-skill.md"
".claude/commands/add-or-update-skill.md"
]
},
"moduleFiles": {
@@ -211,7 +211,7 @@
"workflow-pack": [
".claude/commands/feature-development.md",
".claude/commands/refactoring.md",
".claude/commands/add-new-skill.md"
".claude/commands/add-or-update-skill.md"
]
},
"files": [
@@ -297,8 +297,8 @@
},
{
"moduleId": "workflow-pack",
"path": ".claude/commands/add-new-skill.md",
"description": "Workflow command scaffold for add-new-skill."
"path": ".claude/commands/add-or-update-skill.md",
"description": "Workflow command scaffold for add-or-update-skill."
}
],
"workflows": [
@@ -311,8 +311,8 @@
"path": ".claude/commands/refactoring.md"
},
{
"command": "add-new-skill",
"path": ".claude/commands/add-new-skill.md"
"command": "add-or-update-skill",
"path": ".claude/commands/add-or-update-skill.md"
}
],
"adapters": {
@@ -322,7 +322,7 @@
"commandPaths": [
".claude/commands/feature-development.md",
".claude/commands/refactoring.md",
".claude/commands/add-new-skill.md"
".claude/commands/add-or-update-skill.md"
]
},
"codex": {

View File

@@ -10,5 +10,5 @@
"javascript"
],
"suggestedBy": "ecc-tools-repo-analysis",
"createdAt": "2026-04-01T22:52:48.730Z"
"createdAt": "2026-04-01T23:06:31.168Z"
}

View File

@@ -18,4 +18,4 @@ Use this when the task is documentation-heavy, source-sensitive, or requires bro
- Primary language: JavaScript
- Framework: Not detected
- Workflows detected: 9
- Workflows detected: 8

View File

@@ -4,7 +4,7 @@ Generated by ECC Tools from repository history. Review before treating it as a h
## Commit Workflow
- Prefer `conventional` commit messaging with prefixes such as fix, feat, docs, chore.
- Prefer `mixed` commit messaging with prefixes such as fix, feat, docs, chore.
- Keep new changes aligned with the existing pull-request and review flow already present in the repo.
## Architecture
@@ -26,7 +26,7 @@ Generated by ECC Tools from repository history. Review before treating it as a h
- feature-development: Standard feature implementation workflow
- refactoring: Code refactoring and cleanup workflow
- add-new-skill: Adds a new skill to the codebase, typically as a new agent capability or workflow module.
- add-or-update-skill: Adds a new skill or updates an existing skill for an agentic workflow, including documentation and sometimes related manifests.
## Review Reminder

View File

@@ -5,159 +5,173 @@
## Overview
This skill teaches the core development patterns, coding conventions, and common workflows used in the `everything-claude-code` repository. The codebase is primarily JavaScript, with no major framework, and is organized around modular skills, agent definitions, command workflows, and extensible install targets. The repository emphasizes clear documentation, conventional commits, and maintainable architecture for agent and workflow development.
This skill documents the core development patterns, coding conventions, and agentic workflows used in the `everything-claude-code` (ECC) repository. The project is written in JavaScript (no framework detected) and implements modular, agent-driven automation and installable skills. This guide covers how to contribute new skills, commands, install targets, agent definitions, and more, following the repository's conventions and workflows.
## Coding Conventions
- **File Naming:**
Use `camelCase` for JavaScript files and directories.
*Example:*
```
scripts/lib/installTargets.js
agentPrompts.md
```
ECC follows consistent JavaScript coding and repository organization conventions:
- **Import Style:**
Use **relative imports** for modules.
*Example:*
### File Naming
- Use **camelCase** for JavaScript files and modules.
- Example: `myModule.js`, `installTarget.js`
### Import Style
- Use **relative imports** for internal modules.
```js
const installTarget = require('../lib/installTargets');
// Good
const utils = require('./utils');
import { doThing } from '../lib/doThing.js';
```
- **Export Style:**
Both CommonJS (`module.exports`) and ES module (`export`) styles are present.
*Example (CommonJS):*
### Export Style
- Both **CommonJS** and **ES module** exports are used, depending on context.
```js
module.exports = function mySkill() { ... };
```
*Example (ES Module):*
```js
export function mySkill() { ... }
// CommonJS
module.exports = function doSomething() { ... };
// ES Module
export function doSomethingElse() { ... }
```
- **Commit Messages:**
Use [Conventional Commits](https://www.conventionalcommits.org/).
Prefixes: `fix`, `feat`, `docs`, `chore`
*Example:*
```
feat: add Gemini install target support
fix: correct agent prompt registration logic
```
### Commit Messages
- **Documentation:**
Each skill or agent should have a `SKILL.md` or `.md` documentation file explaining its purpose and usage.
- Prefix with `fix:`, `feat:`, `docs:`, or `chore:`
- Keep messages concise (average ~56 characters)
```
feat: add support for new install target
fix: resolve agent prompt parsing bug
```
## Workflows
### Add New Skill
**Trigger:** When introducing a new skill for agents or workflows
### Add or Update a Skill
**Trigger:** When introducing or updating a skill for agentic workflows
**Command:** `/add-skill`
1. Create a new `SKILL.md` file under `skills/`, `.agents/skills/`, or `.claude/skills/`.
2. Document the skill's purpose, usage, and configuration.
3. Optionally update manifests or documentation if the skill is significant.
1. Create or update a `SKILL.md` file under `skills/{skill-name}/` or `.agents/skills/{skill-name}/`.
2. Optionally update `AGENTS.md`, `README.md`, and localized docs (e.g., `README.zh-CN.md`).
3. Update `manifests/install-modules.json` and/or `install-components.json` if the skill is installable.
4. Optionally add or update related agent markdown files.
5. Optionally update tests or scripts if the skill introduces new hooks or behaviors.
*Example:*
```
skills/myNewSkill/SKILL.md
**Example:**
```shell
mkdir -p skills/myNewSkill
touch skills/myNewSkill/SKILL.md
# Edit SKILL.md with documentation
```
---
### Add New Agent or Agent Prompt
**Trigger:** When introducing a new agent persona or capability
**Command:** `/add-agent`
### Add or Update a Command Workflow
1. Create a new agent definition (e.g., `agents/myAgent.md` or `.opencode/prompts/agents/myAgent.txt`).
2. Register the agent in the relevant configuration file (e.g., `.opencode/opencode.json`).
3. Update `AGENTS.md` or related documentation.
*Example:*
```
agents/supportAgent.md
```
---
### Add or Update Command Workflow
**Trigger:** When introducing or improving a workflow command
**Trigger:** When adding or updating a repeatable workflow command
**Command:** `/add-command`
1. Create or update a command file under `commands/` (e.g., `commands/review.md`).
2. Optionally update related documentation or scripts.
3. Address review feedback and refine command logic.
1. Create or update a markdown file in `commands/` (e.g., `prp-*.md`, `gan-*.md`, `santa-loop.md`).
2. Document workflow phases, usage, and outputs in the file.
3. Optionally update related skills or agent definitions.
4. Optionally add shell scripts or orchestrators if automation is needed.
5. Optionally update `AGENTS.md` or `README.md` to reference the new command.
**Example:**
```shell
touch commands/prp-myworkflow.md
# Document the workflow steps in markdown
```
---
### Add Install Target or Adapter
**Trigger:** When supporting a new platform or integration
### Add or Update an Install Target
**Trigger:** When supporting a new IDE/platform or updating install logic
**Command:** `/add-install-target`
1. Add new install scripts and documentation under a dot-directory (e.g., `.gemini/`, `.codebuddy/`).
2. Update `manifests/install-modules.json` and relevant schema files.
3. Implement or update `scripts/lib/install-targets/*.js` for the new target.
4. Add or update tests for the install target.
1. Add or update install scripts (`install.sh`, `install.js`, `uninstall.sh`, `uninstall.js`) in a new or existing directory (e.g., `.codebuddy/`).
2. Update `manifests/install-modules.json` and `schemas/ecc-install-config.schema.json`.
3. Update `scripts/lib/install-manifests.js` and `scripts/lib/install-targets/{target}.js`.
4. Add or update tests for install targets.
5. Optionally update `README.md` or `AGENTS.md`.
*Example:*
```
.gemini/install.sh
scripts/lib/install-targets/gemini.js
tests/lib/install-targets.test.js
**Example:**
```shell
mkdir -p .codebuddy
touch .codebuddy/install.sh
# Implement install logic
```
---
### Refactor or Collapse Commands to Skills
**Trigger:** When modernizing command logic under the skills architecture
**Command:** `/refactor-to-skill`
### Update Hooks and Hook Tests
1. Update or remove `commands/*.md` files.
2. Add or update `skills/*/SKILL.md` files.
3. Update documentation (`README.md`, `AGENTS.md`, `WORKING-CONTEXT.md`, etc.).
4. Update manifests if required.
**Trigger:** When refactoring, fixing, or extending system hooks
**Command:** `/update-hook`
1. Edit `hooks/hooks.json` to change configuration or add/remove hooks.
2. Edit or add `scripts/hooks/*.js` to implement hook logic.
3. Edit or add `tests/hooks/*.test.js` to cover new or changed behaviors.
4. Optionally update related scripts or documentation.
**Example:**
```json
// hooks/hooks.json
{
"pre-commit": ["format", "typecheck"]
}
```
---
### Documentation and Guidance Update
**Trigger:** When clarifying, updating, or adding documentation
**Command:** `/update-docs`
### Dependency Bump via Dependabot
1. Edit or create documentation files (`README.md`, `WORKING-CONTEXT.md`, `docs/*.md`, etc.).
2. Sync or update guidance in multiple language versions if needed.
3. Optionally update related configuration or manifest files.
**Trigger:** When updating dependencies for security or features
**Command:** `/bump-dependency`
1. Update dependency version in `package.json`, `yarn.lock`, or workflow YAML files.
2. Commit with a standardized message (often by dependabot).
3. Optionally update related documentation or changelogs.
**Example:**
```json
// package.json
"dependencies": {
"some-lib": "^2.0.0"
}
```
---
### CI/CD Workflow Update
**Trigger:** When improving or fixing CI/CD processes
**Command:** `/update-ci`
### Add or Update Agent Definition
1. Edit `.github/workflows/*.yml` files.
2. Update lockfiles (`package-lock.json`, `yarn.lock`) or validation scripts.
3. Update or add test files for CI/CD logic.
**Trigger:** When adding or modifying agent definitions/prompts
**Command:** `/add-agent`
---
1. Add or update agent markdown files (`agents/*.md`).
2. Add or update prompt files (`.opencode/prompts/agents/*.txt`).
3. Update `.opencode/opencode.json` to register new agents.
4. Update `AGENTS.md` to document new agents.
5. Optionally update related skills or orchestrators.
**Example:**
```shell
touch agents/myAgent.md
touch .opencode/prompts/agents/myAgent.txt
```
## Testing Patterns
- **Test Files:**
Test files follow the pattern `*.test.js`.
- **Framework:**
No specific testing framework detected; structure your tests in standard Node.js or your preferred test runner.
*Example:*
```
tests/lib/install-targets.test.js
```
- **Test Example:**
- Test files follow the pattern `*.test.js`.
- Testing framework is **unknown** (not detected), but test files are placed alongside code or in `tests/` directories.
- Example test file:
```js
// install-targets.test.js
const installTarget = require('../../scripts/lib/install-targets/gemini');
test('should install Gemini target', () => {
expect(installTarget()).toBe(true);
// tests/hooks/formatHook.test.js
const formatHook = require('../../scripts/hooks/formatHook');
test('should format code correctly', () => {
// test implementation
});
```
@@ -165,11 +179,10 @@ tests/lib/install-targets.test.js
| Command | Purpose |
|--------------------|----------------------------------------------------------------|
| /add-skill | Add a new skill module and document it |
| /add-agent | Add a new agent definition or prompt |
| /add-command | Add or update a command workflow |
| /add-install-target| Add a new install target or adapter |
| /refactor-to-skill | Refactor commands into skill-based modules |
| /update-docs | Update documentation or guidance files |
| /update-ci | Update CI/CD workflows, lockfiles, or validation scripts |
| /add-skill | Add or update a skill and its documentation |
| /add-command | Add or update a workflow command |
| /add-install-target| Add or update an install target (IDE/platform/environment) |
| /update-hook | Refactor, fix, or extend system hooks and their tests |
| /bump-dependency | Update dependency versions in package or workflow files |
| /add-agent | Add or update agent definitions and prompts |
```

View File

@@ -9,7 +9,7 @@
"commandFiles": [
".claude/commands/feature-development.md",
".claude/commands/refactoring.md",
".claude/commands/add-new-skill.md"
".claude/commands/add-or-update-skill.md"
],
"updatedAt": "2026-04-01T22:51:43.152Z"
"updatedAt": "2026-04-01T23:05:46.781Z"
}

View File

@@ -59,6 +59,8 @@ Public ECC plugin repo for agents, skills, commands, hooks, rules, install surfa
- Direct-port candidates landed after audit:
- `#1078` hook-id dedupe for managed Claude hook reinstalls
- `#844` ui-demo skill
- `#1110` install-time Claude hook root resolution
- `#1106` portable Codex Context7 key extraction
- Port or rebuild inside ECC after full audit:
- `#894` Jira integration
- `#814` + `#808` rebuild as a single consolidated notifications lane for Opencode and cross-harness surfaces
@@ -97,3 +99,6 @@ Keep this file detailed for only the current sprint, blockers, and next actions.
- 2026-04-01: Collapsed the obvious command/skill duplicates into thin legacy shims so `skills/` now hold the maintained bodies for NanoClaw, context-budget, DevFleet, docs lookup, E2E, evals, orchestration, prompt optimization, rules distillation, TDD, and verification.
- 2026-04-01: Ported the self-contained core of `#844` directly into `main` as `skills/ui-demo/SKILL.md` and registered it under the `media-generation` install module instead of merging the PR wholesale.
- 2026-04-01: Added the first connected-workflow operator lane as ECC-native skills instead of leaving the surface as raw plugins or APIs: `workspace-surface-audit`, `customer-billing-ops`, `project-flow-ops`, and `google-workspace-ops`. These are tracked under the new `operator-workflows` install module.
- 2026-04-01: Direct-ported the real fix from the unresolved hook-path PR lane into the active installer. Claude installs now replace `${CLAUDE_PLUGIN_ROOT}` with the concrete install root in both `settings.json` and the copied `hooks/hooks.json`, which keeps PreToolUse/PostToolUse hooks working outside plugin-managed env injection.
- 2026-04-01: Replaced the GNU-only `grep -P` parser in `scripts/sync-ecc-to-codex.sh` with a portable Node parser for Context7 key extraction. Added source-level regression coverage so BSD/macOS syncs do not drift back to non-portable parsing.
- 2026-04-01: Targeted regression suite after the direct ports is green: `tests/scripts/install-apply.test.js`, `tests/scripts/sync-ecc-to-codex.test.js`, and `tests/scripts/codex-hooks.test.js`.

View File

@@ -20,16 +20,43 @@ function readJsonObject(filePath, label) {
return parsed;
}
function buildLegacyHookSignature(entry) {
function replacePluginRootPlaceholders(value, pluginRoot) {
if (!pluginRoot) {
return value;
}
if (typeof value === 'string') {
return value.split('${CLAUDE_PLUGIN_ROOT}').join(pluginRoot);
}
if (Array.isArray(value)) {
return value.map(item => replacePluginRootPlaceholders(item, pluginRoot));
}
if (value && typeof value === 'object') {
return Object.fromEntries(
Object.entries(value).map(([key, nestedValue]) => [
key,
replacePluginRootPlaceholders(nestedValue, pluginRoot),
])
);
}
return value;
}
function buildLegacyHookSignature(entry, pluginRoot) {
if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
return null;
}
if (typeof entry.matcher !== 'string' || !Array.isArray(entry.hooks)) {
const normalizedEntry = replacePluginRootPlaceholders(entry, pluginRoot);
if (typeof normalizedEntry.matcher !== 'string' || !Array.isArray(normalizedEntry.hooks)) {
return null;
}
const hookSignature = entry.hooks.map(hook => JSON.stringify({
const hookSignature = normalizedEntry.hooks.map(hook => JSON.stringify({
type: hook && typeof hook === 'object' ? hook.type : undefined,
command: hook && typeof hook === 'object' ? hook.command : undefined,
timeout: hook && typeof hook === 'object' ? hook.timeout : undefined,
@@ -37,33 +64,35 @@ function buildLegacyHookSignature(entry) {
}));
return JSON.stringify({
matcher: entry.matcher,
matcher: normalizedEntry.matcher,
hooks: hookSignature,
});
}
function getHookEntryAliases(entry) {
function getHookEntryAliases(entry, pluginRoot) {
const aliases = [];
if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
return aliases;
}
if (typeof entry.id === 'string' && entry.id.trim().length > 0) {
aliases.push(`id:${entry.id.trim()}`);
const normalizedEntry = replacePluginRootPlaceholders(entry, pluginRoot);
if (typeof normalizedEntry.id === 'string' && normalizedEntry.id.trim().length > 0) {
aliases.push(`id:${normalizedEntry.id.trim()}`);
}
const legacySignature = buildLegacyHookSignature(entry);
const legacySignature = buildLegacyHookSignature(normalizedEntry, pluginRoot);
if (legacySignature) {
aliases.push(`legacy:${legacySignature}`);
}
aliases.push(`json:${JSON.stringify(entry)}`);
aliases.push(`json:${JSON.stringify(normalizedEntry)}`);
return aliases;
}
function mergeHookEntries(existingEntries, incomingEntries) {
function mergeHookEntries(existingEntries, incomingEntries, pluginRoot) {
const mergedEntries = [];
const seenEntries = new Set();
@@ -76,7 +105,7 @@ function mergeHookEntries(existingEntries, incomingEntries) {
continue;
}
const aliases = getHookEntryAliases(entry);
const aliases = getHookEntryAliases(entry, pluginRoot);
if (aliases.some(alias => seenEntries.has(alias))) {
continue;
}
@@ -84,7 +113,7 @@ function mergeHookEntries(existingEntries, incomingEntries) {
for (const alias of aliases) {
seenEntries.add(alias);
}
mergedEntries.push(entry);
mergedEntries.push(replacePluginRootPlaceholders(entry, pluginRoot));
}
return mergedEntries;
@@ -100,6 +129,7 @@ function buildMergedSettings(plan) {
return null;
}
const pluginRoot = plan.targetRoot;
const hooksDestinationPath = path.join(plan.targetRoot, 'hooks', 'hooks.json');
const hooksSourcePath = findHooksSourcePath(plan, hooksDestinationPath) || hooksDestinationPath;
if (!fs.existsSync(hooksSourcePath)) {
@@ -107,7 +137,7 @@ function buildMergedSettings(plan) {
}
const hooksConfig = readJsonObject(hooksSourcePath, 'hooks config');
const incomingHooks = hooksConfig.hooks;
const incomingHooks = replacePluginRootPlaceholders(hooksConfig.hooks, pluginRoot);
if (!incomingHooks || typeof incomingHooks !== 'object' || Array.isArray(incomingHooks)) {
throw new Error(`Invalid hooks config at ${hooksSourcePath}: expected "hooks" to be a JSON object`);
}
@@ -126,7 +156,7 @@ function buildMergedSettings(plan) {
for (const [eventName, incomingEntries] of Object.entries(incomingHooks)) {
const currentEntries = Array.isArray(existingHooks[eventName]) ? existingHooks[eventName] : [];
const nextEntries = Array.isArray(incomingEntries) ? incomingEntries : [];
mergedHooks[eventName] = mergeHookEntries(currentEntries, nextEntries);
mergedHooks[eventName] = mergeHookEntries(currentEntries, nextEntries, pluginRoot);
}
const mergedSettings = {
@@ -137,6 +167,11 @@ function buildMergedSettings(plan) {
return {
settingsPath,
mergedSettings,
hooksDestinationPath,
resolvedHooksConfig: {
...hooksConfig,
hooks: incomingHooks,
},
};
}
@@ -149,6 +184,12 @@ function applyInstallPlan(plan) {
}
if (mergedSettingsPlan) {
fs.mkdirSync(path.dirname(mergedSettingsPlan.hooksDestinationPath), { recursive: true });
fs.writeFileSync(
mergedSettingsPlan.hooksDestinationPath,
JSON.stringify(mergedSettingsPlan.resolvedHooksConfig, null, 2) + '\n',
'utf8'
);
fs.mkdirSync(path.dirname(mergedSettingsPlan.settingsPath), { recursive: true });
fs.writeFileSync(
mergedSettingsPlan.settingsPath,

View File

@@ -106,7 +106,23 @@ extract_toml_value() {
extract_context7_key() {
local file="$1"
grep -oP -- '--key",[[:space:]]*"\K[^"]+' "$file" | head -n 1 || true
node - "$file" <<'EOF'
const fs = require('fs');
const filePath = process.argv[2];
let source = '';
try {
source = fs.readFileSync(filePath, 'utf8');
} catch {
process.exit(0);
}
const match = source.match(/--key",\s*"([^"]+)"/);
if (match && match[1]) {
process.stdout.write(`${match[1]}\n`);
}
EOF
}
generate_prompt_file() {

View File

@@ -353,6 +353,45 @@ function runTests() {
}
})) passed++; else failed++;
if (test('resolves CLAUDE_PLUGIN_ROOT placeholders in installed claude hooks', () => {
const homeDir = createTempDir('install-apply-home-');
const projectDir = createTempDir('install-apply-project-');
try {
const result = run(['--profile', 'core'], { cwd: projectDir, homeDir });
assert.strictEqual(result.code, 0, result.stderr);
const claudeRoot = path.join(homeDir, '.claude');
const settings = readJson(path.join(claudeRoot, 'settings.json'));
const installedHooks = readJson(path.join(claudeRoot, 'hooks', 'hooks.json'));
const autoTmuxEntry = settings.hooks.PreToolUse.find(entry => entry.id === 'pre:bash:auto-tmux-dev');
assert.ok(autoTmuxEntry, 'settings.json should include the auto tmux hook');
assert.ok(
autoTmuxEntry.hooks[0].command.includes(path.join(claudeRoot, 'scripts', 'hooks', 'auto-tmux-dev.js')),
'settings.json should use the installed Claude root for hook commands'
);
assert.ok(
!autoTmuxEntry.hooks[0].command.includes('${CLAUDE_PLUGIN_ROOT}'),
'settings.json should not retain CLAUDE_PLUGIN_ROOT placeholders after install'
);
const installedAutoTmuxEntry = installedHooks.hooks.PreToolUse.find(entry => entry.id === 'pre:bash:auto-tmux-dev');
assert.ok(installedAutoTmuxEntry, 'hooks/hooks.json should include the auto tmux hook');
assert.ok(
installedAutoTmuxEntry.hooks[0].command.includes(path.join(claudeRoot, 'scripts', 'hooks', 'auto-tmux-dev.js')),
'hooks/hooks.json should use the installed Claude root for hook commands'
);
assert.ok(
!installedAutoTmuxEntry.hooks[0].command.includes('${CLAUDE_PLUGIN_ROOT}'),
'hooks/hooks.json should not retain CLAUDE_PLUGIN_ROOT placeholders after install'
);
} finally {
cleanup(homeDir);
cleanup(projectDir);
}
})) passed++; else failed++;
if (test('preserves existing settings fields and hook entries when merging hooks', () => {
const homeDir = createTempDir('install-apply-home-');
const projectDir = createTempDir('install-apply-project-');

View File

@@ -74,6 +74,15 @@ function runTests() {
assert.ok(!source.includes('run_or_echo cp -R "$skill_dir" "$dest"'), 'skill sync cp should be removed');
})) passed++; else failed++;
if (test('sync script avoids GNU-only grep -P parsing', () => {
assert.ok(!source.includes('grep -oP'), 'sync-ecc-to-codex.sh should remain portable across BSD and GNU environments');
})) passed++; else failed++;
if (test('extract_context7_key uses a portable parser', () => {
assert.ok(source.includes('extract_context7_key() {'), 'Expected extract_context7_key helper');
assert.ok(source.includes('node - "$file"'), 'extract_context7_key should use Node-based parsing');
})) passed++; else failed++;
console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
process.exit(failed > 0 ? 1 : 0);
}