mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-02 15:13:28 +08:00
Compare commits
16 Commits
ecc-tools/
...
ecc-tools/
| Author | SHA1 | Date | |
|---|---|---|---|
|
cdbaf9feff | ||
|
|
8f2170f9cf | ||
|
|
7ac28b45eb | ||
|
|
d7bffc3f5a | ||
|
|
e9aeeb13d7 | ||
|
|
d0103898bb | ||
|
|
4356273cfa | ||
|
|
b5907ccfbd | ||
|
|
7e0d803bed | ||
|
|
4b6de88b90 | ||
|
|
0f2089e2ad | ||
|
|
1e1edd1b9e | ||
|
|
a68feb7ac7 | ||
|
|
eb564ee4b6 | ||
|
|
ab19584689 | ||
|
|
dba5ae779b |
@@ -5,162 +5,184 @@
|
||||
|
||||
## Overview
|
||||
|
||||
This skill introduces the core development patterns, coding conventions, and common workflows for contributing to the `everything-claude-code` repository. The project is JavaScript-based, with no framework dependencies, and emphasizes modularity, agentic skills, and workflow automation. This guide covers file organization, commit conventions, code style, workflow steps, and testing patterns to help you contribute effectively and consistently.
|
||||
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 folders.
|
||||
- Example: `mySkill.js`, `installTarget.js`
|
||||
- **Import Style:** Use relative imports.
|
||||
- Example:
|
||||
```js
|
||||
const helper = require('./utils/helper');
|
||||
```
|
||||
- **Export Style:** Mixed (both CommonJS and ES module styles may be present).
|
||||
- Example (CommonJS):
|
||||
```js
|
||||
module.exports = function mySkill() { ... };
|
||||
```
|
||||
- Example (ESM):
|
||||
```js
|
||||
export default function mySkill() { ... }
|
||||
```
|
||||
- **Commit Messages:** Follow [Conventional Commits](https://www.conventionalcommits.org/) with prefixes such as `fix`, `feat`, `docs`, `chore`.
|
||||
- Example: `feat: add support for new install target`
|
||||
- **Test Files:** Use the pattern `*.test.js` for test files.
|
||||
ECC follows consistent JavaScript coding and repository organization conventions:
|
||||
|
||||
### File Naming
|
||||
|
||||
- Use **camelCase** for JavaScript files and modules.
|
||||
- Example: `myModule.js`, `installTarget.js`
|
||||
|
||||
### Import Style
|
||||
|
||||
- Use **relative imports** for internal modules.
|
||||
```js
|
||||
// Good
|
||||
const utils = require('./utils');
|
||||
import { doThing } from '../lib/doThing.js';
|
||||
```
|
||||
|
||||
### Export Style
|
||||
|
||||
- Both **CommonJS** and **ES module** exports are used, depending on context.
|
||||
```js
|
||||
// CommonJS
|
||||
module.exports = function doSomething() { ... };
|
||||
|
||||
// ES Module
|
||||
export function doSomethingElse() { ... }
|
||||
```
|
||||
|
||||
### Commit Messages
|
||||
|
||||
- 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 or Update a Skill
|
||||
**Trigger:** When introducing or updating a workflow, agent, or capability
|
||||
|
||||
**Trigger:** When introducing or updating a skill for agentic workflows
|
||||
**Command:** `/add-skill`
|
||||
|
||||
1. Create or update a `SKILL.md` file in one of:
|
||||
- `skills/<skill-name>/SKILL.md`
|
||||
- `.agents/skills/<skill-name>/SKILL.md`
|
||||
- `.claude/skills/<skill-name>/SKILL.md`
|
||||
2. Optionally update `AGENTS.md`, `README.md`, or `manifests/install-modules.json` to reference the new skill.
|
||||
3. Document the skill's usage and integration points.
|
||||
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:**
|
||||
```bash
|
||||
/add-skill
|
||||
```shell
|
||||
mkdir -p skills/myNewSkill
|
||||
touch skills/myNewSkill/SKILL.md
|
||||
# Edit SKILL.md with documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update a Command
|
||||
**Trigger:** When adding a new CLI command, workflow, or extending command capabilities
|
||||
### Add or Update a Command Workflow
|
||||
|
||||
**Trigger:** When adding or updating a repeatable workflow command
|
||||
**Command:** `/add-command`
|
||||
|
||||
1. Create or update a markdown file in `commands/` (e.g., `commands/<command>.md`).
|
||||
2. Optionally update related documentation (`README.md`, `AGENTS.md`).
|
||||
3. If the command is part of a workflow, update or create associated artifacts or scripts.
|
||||
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:**
|
||||
```bash
|
||||
/add-command
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update an Agent
|
||||
**Trigger:** When introducing a new agent or updating agent logic
|
||||
**Command:** `/add-agent`
|
||||
|
||||
1. Create or update agent definition markdown in `agents/<agent-name>.md` or `.opencode/prompts/agents/<agent>.txt`.
|
||||
2. Register or update the agent in `opencode.json` or related config.
|
||||
3. Update `AGENTS.md` with new agent details.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/add-agent
|
||||
```shell
|
||||
touch commands/prp-myworkflow.md
|
||||
# Document the workflow steps in markdown
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update an Install Target
|
||||
**Trigger:** When supporting a new platform/tool for installation/integration
|
||||
|
||||
**Trigger:** When supporting a new IDE/platform or updating install logic
|
||||
**Command:** `/add-install-target`
|
||||
|
||||
1. Create or update install scripts (`.sh`/`.js`) and documentation in a dot-directory (e.g., `.codebuddy/`, `.gemini/`).
|
||||
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`.
|
||||
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:**
|
||||
```bash
|
||||
/add-install-target
|
||||
```shell
|
||||
mkdir -p .codebuddy
|
||||
touch .codebuddy/install.sh
|
||||
# Implement install logic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update CI Workflow
|
||||
**Trigger:** When updating CI workflows, adding new checks, or bumping dependencies
|
||||
**Command:** `/update-ci`
|
||||
### Update Hooks and Hook Tests
|
||||
|
||||
1. Edit or add files in `.github/workflows/`.
|
||||
2. Update `package.json` or `yarn.lock` if dependency-related.
|
||||
3. Test CI to ensure the new workflow or dependency works as intended.
|
||||
**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:**
|
||||
```bash
|
||||
/update-ci
|
||||
```json
|
||||
// hooks/hooks.json
|
||||
{
|
||||
"pre-commit": ["format", "typecheck"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Update Hooks or Validation Scripts
|
||||
**Trigger:** When improving or fixing pre/post hooks, or validation logic for edits and CI
|
||||
**Command:** `/update-hooks`
|
||||
### Dependency Bump via Dependabot
|
||||
|
||||
1. Edit `hooks/hooks.json` and supporting scripts in `scripts/hooks/`.
|
||||
2. Update or add tests in `tests/hooks/` or `tests/scripts/`.
|
||||
3. Optionally update related documentation.
|
||||
**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:**
|
||||
```bash
|
||||
/update-hooks
|
||||
```json
|
||||
// package.json
|
||||
"dependencies": {
|
||||
"some-lib": "^2.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update Documentation
|
||||
**Trigger:** When documenting new workflows, updating guides, or adding troubleshooting info
|
||||
**Command:** `/update-docs`
|
||||
### Add or Update Agent Definition
|
||||
|
||||
1. Edit or add markdown files in `docs/`, `WORKING-CONTEXT.md`, or `the-shortform-guide.md`.
|
||||
2. Update `README.md` and/or `README.zh-CN.md`.
|
||||
3. Optionally update related skill or agent docs.
|
||||
**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:**
|
||||
```bash
|
||||
/update-docs
|
||||
```shell
|
||||
touch agents/myAgent.md
|
||||
touch .opencode/prompts/agents/myAgent.txt
|
||||
```
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
- **Test Files:** Place tests in the same directory as the code or in a `tests/` directory, using the `*.test.js` naming convention.
|
||||
- **Framework:** No specific testing framework detected; use standard JavaScript test runners (e.g., Jest, Mocha) as appropriate.
|
||||
- **Example Test File:**
|
||||
```js
|
||||
// mySkill.test.js
|
||||
const mySkill = require('./mySkill');
|
||||
|
||||
test('should return expected result', () => {
|
||||
expect(mySkill('input')).toBe('expected output');
|
||||
});
|
||||
```
|
||||
- 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
|
||||
// tests/hooks/formatHook.test.js
|
||||
const formatHook = require('../../scripts/hooks/formatHook');
|
||||
test('should format code correctly', () => {
|
||||
// test implementation
|
||||
});
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------------------|--------------------------------------------------------------|
|
||||
| /add-skill | Add or update a skill (workflow, agent, or capability) |
|
||||
| /add-command | Add or update a command file for new or extended workflows |
|
||||
| /add-agent | Add or update an agent definition |
|
||||
| /add-install-target | Add or update an install target for external integrations |
|
||||
| /update-ci | Add or update CI/CD workflow files or dependencies |
|
||||
| /update-hooks | Update hooks or validation scripts |
|
||||
| /update-docs | Add or update documentation |
|
||||
| Command | Purpose |
|
||||
|--------------------|----------------------------------------------------------------|
|
||||
| /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 |
|
||||
```
|
||||
|
||||
@@ -10,16 +10,16 @@ Use this workflow when working on **add-or-update-skill** in `everything-claude-
|
||||
|
||||
## Goal
|
||||
|
||||
Adds a new skill or updates an existing skill, typically for a new workflow, agent, or capability.
|
||||
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`
|
||||
- `.claude/skills/*/SKILL.md`
|
||||
- `AGENTS.md`
|
||||
- `README.md`
|
||||
- `manifests/install-modules.json`
|
||||
- `README.zh-CN.md`
|
||||
- `docs/zh-CN/AGENTS.md`
|
||||
|
||||
## Suggested Sequence
|
||||
|
||||
@@ -30,9 +30,11 @@ Adds a new skill or updates an existing skill, typically for a new workflow, age
|
||||
|
||||
## Typical Commit Signals
|
||||
|
||||
- Create or update a SKILL.md file in skills/<skill-name>/ or .agents/skills/<skill-name>/ or .claude/skills/<skill-name>/
|
||||
- Optionally update AGENTS.md, README.md, or manifests/install-modules.json to reference the new skill
|
||||
- Document the skill's usage and integration points
|
||||
- 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
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"version": "1.3",
|
||||
"schemaVersion": "1.0",
|
||||
"generatedBy": "ecc-tools",
|
||||
"generatedAt": "2026-04-01T22:57:31.655Z",
|
||||
"generatedAt": "2026-04-01T23:05:46.781Z",
|
||||
"repo": "https://github.com/affaan-m/everything-claude-code",
|
||||
"profiles": {
|
||||
"requested": "full",
|
||||
|
||||
@@ -10,5 +10,5 @@
|
||||
"javascript"
|
||||
],
|
||||
"suggestedBy": "ecc-tools-repo-analysis",
|
||||
"createdAt": "2026-04-01T22:58:08.299Z"
|
||||
"createdAt": "2026-04-01T23:06:31.168Z"
|
||||
}
|
||||
@@ -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
|
||||
@@ -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-or-update-skill: Adds a new skill or updates an existing skill, typically for a new workflow, agent, or capability.
|
||||
- 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
|
||||
|
||||
|
||||
@@ -5,162 +5,184 @@
|
||||
|
||||
## Overview
|
||||
|
||||
This skill introduces the core development patterns, coding conventions, and common workflows for contributing to the `everything-claude-code` repository. The project is JavaScript-based, with no framework dependencies, and emphasizes modularity, agentic skills, and workflow automation. This guide covers file organization, commit conventions, code style, workflow steps, and testing patterns to help you contribute effectively and consistently.
|
||||
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 folders.
|
||||
- Example: `mySkill.js`, `installTarget.js`
|
||||
- **Import Style:** Use relative imports.
|
||||
- Example:
|
||||
```js
|
||||
const helper = require('./utils/helper');
|
||||
```
|
||||
- **Export Style:** Mixed (both CommonJS and ES module styles may be present).
|
||||
- Example (CommonJS):
|
||||
```js
|
||||
module.exports = function mySkill() { ... };
|
||||
```
|
||||
- Example (ESM):
|
||||
```js
|
||||
export default function mySkill() { ... }
|
||||
```
|
||||
- **Commit Messages:** Follow [Conventional Commits](https://www.conventionalcommits.org/) with prefixes such as `fix`, `feat`, `docs`, `chore`.
|
||||
- Example: `feat: add support for new install target`
|
||||
- **Test Files:** Use the pattern `*.test.js` for test files.
|
||||
ECC follows consistent JavaScript coding and repository organization conventions:
|
||||
|
||||
### File Naming
|
||||
|
||||
- Use **camelCase** for JavaScript files and modules.
|
||||
- Example: `myModule.js`, `installTarget.js`
|
||||
|
||||
### Import Style
|
||||
|
||||
- Use **relative imports** for internal modules.
|
||||
```js
|
||||
// Good
|
||||
const utils = require('./utils');
|
||||
import { doThing } from '../lib/doThing.js';
|
||||
```
|
||||
|
||||
### Export Style
|
||||
|
||||
- Both **CommonJS** and **ES module** exports are used, depending on context.
|
||||
```js
|
||||
// CommonJS
|
||||
module.exports = function doSomething() { ... };
|
||||
|
||||
// ES Module
|
||||
export function doSomethingElse() { ... }
|
||||
```
|
||||
|
||||
### Commit Messages
|
||||
|
||||
- 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 or Update a Skill
|
||||
**Trigger:** When introducing or updating a workflow, agent, or capability
|
||||
|
||||
**Trigger:** When introducing or updating a skill for agentic workflows
|
||||
**Command:** `/add-skill`
|
||||
|
||||
1. Create or update a `SKILL.md` file in one of:
|
||||
- `skills/<skill-name>/SKILL.md`
|
||||
- `.agents/skills/<skill-name>/SKILL.md`
|
||||
- `.claude/skills/<skill-name>/SKILL.md`
|
||||
2. Optionally update `AGENTS.md`, `README.md`, or `manifests/install-modules.json` to reference the new skill.
|
||||
3. Document the skill's usage and integration points.
|
||||
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:**
|
||||
```bash
|
||||
/add-skill
|
||||
```shell
|
||||
mkdir -p skills/myNewSkill
|
||||
touch skills/myNewSkill/SKILL.md
|
||||
# Edit SKILL.md with documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update a Command
|
||||
**Trigger:** When adding a new CLI command, workflow, or extending command capabilities
|
||||
### Add or Update a Command Workflow
|
||||
|
||||
**Trigger:** When adding or updating a repeatable workflow command
|
||||
**Command:** `/add-command`
|
||||
|
||||
1. Create or update a markdown file in `commands/` (e.g., `commands/<command>.md`).
|
||||
2. Optionally update related documentation (`README.md`, `AGENTS.md`).
|
||||
3. If the command is part of a workflow, update or create associated artifacts or scripts.
|
||||
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:**
|
||||
```bash
|
||||
/add-command
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update an Agent
|
||||
**Trigger:** When introducing a new agent or updating agent logic
|
||||
**Command:** `/add-agent`
|
||||
|
||||
1. Create or update agent definition markdown in `agents/<agent-name>.md` or `.opencode/prompts/agents/<agent>.txt`.
|
||||
2. Register or update the agent in `opencode.json` or related config.
|
||||
3. Update `AGENTS.md` with new agent details.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
/add-agent
|
||||
```shell
|
||||
touch commands/prp-myworkflow.md
|
||||
# Document the workflow steps in markdown
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update an Install Target
|
||||
**Trigger:** When supporting a new platform/tool for installation/integration
|
||||
|
||||
**Trigger:** When supporting a new IDE/platform or updating install logic
|
||||
**Command:** `/add-install-target`
|
||||
|
||||
1. Create or update install scripts (`.sh`/`.js`) and documentation in a dot-directory (e.g., `.codebuddy/`, `.gemini/`).
|
||||
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`.
|
||||
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:**
|
||||
```bash
|
||||
/add-install-target
|
||||
```shell
|
||||
mkdir -p .codebuddy
|
||||
touch .codebuddy/install.sh
|
||||
# Implement install logic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update CI Workflow
|
||||
**Trigger:** When updating CI workflows, adding new checks, or bumping dependencies
|
||||
**Command:** `/update-ci`
|
||||
### Update Hooks and Hook Tests
|
||||
|
||||
1. Edit or add files in `.github/workflows/`.
|
||||
2. Update `package.json` or `yarn.lock` if dependency-related.
|
||||
3. Test CI to ensure the new workflow or dependency works as intended.
|
||||
**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:**
|
||||
```bash
|
||||
/update-ci
|
||||
```json
|
||||
// hooks/hooks.json
|
||||
{
|
||||
"pre-commit": ["format", "typecheck"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Update Hooks or Validation Scripts
|
||||
**Trigger:** When improving or fixing pre/post hooks, or validation logic for edits and CI
|
||||
**Command:** `/update-hooks`
|
||||
### Dependency Bump via Dependabot
|
||||
|
||||
1. Edit `hooks/hooks.json` and supporting scripts in `scripts/hooks/`.
|
||||
2. Update or add tests in `tests/hooks/` or `tests/scripts/`.
|
||||
3. Optionally update related documentation.
|
||||
**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:**
|
||||
```bash
|
||||
/update-hooks
|
||||
```json
|
||||
// package.json
|
||||
"dependencies": {
|
||||
"some-lib": "^2.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update Documentation
|
||||
**Trigger:** When documenting new workflows, updating guides, or adding troubleshooting info
|
||||
**Command:** `/update-docs`
|
||||
### Add or Update Agent Definition
|
||||
|
||||
1. Edit or add markdown files in `docs/`, `WORKING-CONTEXT.md`, or `the-shortform-guide.md`.
|
||||
2. Update `README.md` and/or `README.zh-CN.md`.
|
||||
3. Optionally update related skill or agent docs.
|
||||
**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:**
|
||||
```bash
|
||||
/update-docs
|
||||
```shell
|
||||
touch agents/myAgent.md
|
||||
touch .opencode/prompts/agents/myAgent.txt
|
||||
```
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
- **Test Files:** Place tests in the same directory as the code or in a `tests/` directory, using the `*.test.js` naming convention.
|
||||
- **Framework:** No specific testing framework detected; use standard JavaScript test runners (e.g., Jest, Mocha) as appropriate.
|
||||
- **Example Test File:**
|
||||
```js
|
||||
// mySkill.test.js
|
||||
const mySkill = require('./mySkill');
|
||||
|
||||
test('should return expected result', () => {
|
||||
expect(mySkill('input')).toBe('expected output');
|
||||
});
|
||||
```
|
||||
- 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
|
||||
// tests/hooks/formatHook.test.js
|
||||
const formatHook = require('../../scripts/hooks/formatHook');
|
||||
test('should format code correctly', () => {
|
||||
// test implementation
|
||||
});
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------------------|--------------------------------------------------------------|
|
||||
| /add-skill | Add or update a skill (workflow, agent, or capability) |
|
||||
| /add-command | Add or update a command file for new or extended workflows |
|
||||
| /add-agent | Add or update an agent definition |
|
||||
| /add-install-target | Add or update an install target for external integrations |
|
||||
| /update-ci | Add or update CI/CD workflow files or dependencies |
|
||||
| /update-hooks | Update hooks or validation scripts |
|
||||
| /update-docs | Add or update documentation |
|
||||
| Command | Purpose |
|
||||
|--------------------|----------------------------------------------------------------|
|
||||
| /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 |
|
||||
```
|
||||
|
||||
@@ -11,5 +11,5 @@
|
||||
".claude/commands/refactoring.md",
|
||||
".claude/commands/add-or-update-skill.md"
|
||||
],
|
||||
"updatedAt": "2026-04-01T22:57:31.655Z"
|
||||
"updatedAt": "2026-04-01T23:05:46.781Z"
|
||||
}
|
||||
@@ -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`.
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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() {
|
||||
|
||||
@@ -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-');
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user