mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-02 15:13:28 +08:00
Compare commits
15 Commits
ecc-tools/
...
ecc-tools/
| Author | SHA1 | Date | |
|---|---|---|---|
|
a23988866c | ||
|
|
4abc4e8887 | ||
|
|
dc1c46d453 | ||
|
|
7b1bc6d407 | ||
|
|
c89b166538 | ||
|
|
67ea3c5437 | ||
|
|
efd4b37555 | ||
|
|
5fdc208620 | ||
|
|
02ce835abb | ||
|
|
e81df5da4c | ||
|
|
1833739141 | ||
|
|
102d3196c7 | ||
|
|
8bfd408622 | ||
|
|
d67e19e830 | ||
|
|
483aa8530f |
@@ -5,184 +5,162 @@
|
||||
|
||||
## Overview
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
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
|
||||
```
|
||||
- **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.
|
||||
|
||||
## Workflows
|
||||
|
||||
### Add or Update a Skill
|
||||
|
||||
**Trigger:** When introducing or updating a skill for agentic workflows
|
||||
**Trigger:** When introducing or updating a workflow, agent, or capability
|
||||
**Command:** `/add-skill`
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```shell
|
||||
mkdir -p skills/myNewSkill
|
||||
touch skills/myNewSkill/SKILL.md
|
||||
# Edit SKILL.md with documentation
|
||||
```bash
|
||||
/add-skill
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update a Command Workflow
|
||||
|
||||
**Trigger:** When adding or updating a repeatable workflow command
|
||||
### Add or Update a Command
|
||||
**Trigger:** When adding a new CLI command, workflow, or extending command capabilities
|
||||
**Command:** `/add-command`
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```shell
|
||||
touch commands/prp-myworkflow.md
|
||||
# Document the workflow steps in markdown
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update an Install Target
|
||||
|
||||
**Trigger:** When supporting a new IDE/platform or updating install logic
|
||||
**Trigger:** When supporting a new platform/tool for installation/integration
|
||||
**Command:** `/add-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/`).
|
||||
1. Create or update install scripts (`.sh`/`.js`) and documentation in a dot-directory (e.g., `.codebuddy/`, `.gemini/`).
|
||||
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:**
|
||||
```shell
|
||||
mkdir -p .codebuddy
|
||||
touch .codebuddy/install.sh
|
||||
# Implement install logic
|
||||
```bash
|
||||
/add-install-target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Update Hooks and Hook Tests
|
||||
### Add or Update CI Workflow
|
||||
**Trigger:** When updating CI workflows, adding new checks, or bumping dependencies
|
||||
**Command:** `/update-ci`
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
// hooks/hooks.json
|
||||
{
|
||||
"pre-commit": ["format", "typecheck"]
|
||||
}
|
||||
```bash
|
||||
/update-ci
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Dependency Bump via Dependabot
|
||||
### Update Hooks or Validation Scripts
|
||||
**Trigger:** When improving or fixing pre/post hooks, or validation logic for edits and CI
|
||||
**Command:** `/update-hooks`
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
// package.json
|
||||
"dependencies": {
|
||||
"some-lib": "^2.0.0"
|
||||
}
|
||||
```bash
|
||||
/update-hooks
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update Agent Definition
|
||||
### Add or Update Documentation
|
||||
**Trigger:** When documenting new workflows, updating guides, or adding troubleshooting info
|
||||
**Command:** `/update-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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```shell
|
||||
touch agents/myAgent.md
|
||||
touch .opencode/prompts/agents/myAgent.txt
|
||||
```bash
|
||||
/update-docs
|
||||
```
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
- 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
|
||||
});
|
||||
```
|
||||
- **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');
|
||||
});
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| 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 |
|
||||
| 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 |
|
||||
```
|
||||
|
||||
@@ -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 for an agentic workflow, including documentation and sometimes related manifests.
|
||||
Adds a new skill or updates an existing skill, typically for a new workflow, agent, or capability.
|
||||
|
||||
## Common Files
|
||||
|
||||
- `skills/*/SKILL.md`
|
||||
- `.agents/skills/*/SKILL.md`
|
||||
- `.claude/skills/*/SKILL.md`
|
||||
- `AGENTS.md`
|
||||
- `README.md`
|
||||
- `README.zh-CN.md`
|
||||
- `docs/zh-CN/AGENTS.md`
|
||||
- `manifests/install-modules.json`
|
||||
|
||||
## Suggested Sequence
|
||||
|
||||
@@ -30,11 +30,9 @@ Adds a new skill or updates an existing skill for an agentic workflow, including
|
||||
|
||||
## 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
|
||||
- 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
|
||||
|
||||
## Notes
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"version": "1.3",
|
||||
"schemaVersion": "1.0",
|
||||
"generatedBy": "ecc-tools",
|
||||
"generatedAt": "2026-04-01T23:05:46.781Z",
|
||||
"generatedAt": "2026-04-01T22:57:31.655Z",
|
||||
"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-01T23:06:31.168Z"
|
||||
"createdAt": "2026-04-01T22:58:08.299Z"
|
||||
}
|
||||
@@ -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: 8
|
||||
- Workflows detected: 9
|
||||
@@ -4,7 +4,7 @@ Generated by ECC Tools from repository history. Review before treating it as a h
|
||||
|
||||
## Commit Workflow
|
||||
|
||||
- Prefer `mixed` commit messaging with prefixes such as fix, feat, docs, chore.
|
||||
- Prefer `conventional` 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 for an agentic workflow, including documentation and sometimes related manifests.
|
||||
- add-or-update-skill: Adds a new skill or updates an existing skill, typically for a new workflow, agent, or capability.
|
||||
|
||||
## Review Reminder
|
||||
|
||||
|
||||
@@ -5,184 +5,162 @@
|
||||
|
||||
## Overview
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
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
|
||||
```
|
||||
- **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.
|
||||
|
||||
## Workflows
|
||||
|
||||
### Add or Update a Skill
|
||||
|
||||
**Trigger:** When introducing or updating a skill for agentic workflows
|
||||
**Trigger:** When introducing or updating a workflow, agent, or capability
|
||||
**Command:** `/add-skill`
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```shell
|
||||
mkdir -p skills/myNewSkill
|
||||
touch skills/myNewSkill/SKILL.md
|
||||
# Edit SKILL.md with documentation
|
||||
```bash
|
||||
/add-skill
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update a Command Workflow
|
||||
|
||||
**Trigger:** When adding or updating a repeatable workflow command
|
||||
### Add or Update a Command
|
||||
**Trigger:** When adding a new CLI command, workflow, or extending command capabilities
|
||||
**Command:** `/add-command`
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```shell
|
||||
touch commands/prp-myworkflow.md
|
||||
# Document the workflow steps in markdown
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update an Install Target
|
||||
|
||||
**Trigger:** When supporting a new IDE/platform or updating install logic
|
||||
**Trigger:** When supporting a new platform/tool for installation/integration
|
||||
**Command:** `/add-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/`).
|
||||
1. Create or update install scripts (`.sh`/`.js`) and documentation in a dot-directory (e.g., `.codebuddy/`, `.gemini/`).
|
||||
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:**
|
||||
```shell
|
||||
mkdir -p .codebuddy
|
||||
touch .codebuddy/install.sh
|
||||
# Implement install logic
|
||||
```bash
|
||||
/add-install-target
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Update Hooks and Hook Tests
|
||||
### Add or Update CI Workflow
|
||||
**Trigger:** When updating CI workflows, adding new checks, or bumping dependencies
|
||||
**Command:** `/update-ci`
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
// hooks/hooks.json
|
||||
{
|
||||
"pre-commit": ["format", "typecheck"]
|
||||
}
|
||||
```bash
|
||||
/update-ci
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Dependency Bump via Dependabot
|
||||
### Update Hooks or Validation Scripts
|
||||
**Trigger:** When improving or fixing pre/post hooks, or validation logic for edits and CI
|
||||
**Command:** `/update-hooks`
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```json
|
||||
// package.json
|
||||
"dependencies": {
|
||||
"some-lib": "^2.0.0"
|
||||
}
|
||||
```bash
|
||||
/update-hooks
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add or Update Agent Definition
|
||||
### Add or Update Documentation
|
||||
**Trigger:** When documenting new workflows, updating guides, or adding troubleshooting info
|
||||
**Command:** `/update-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.
|
||||
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.
|
||||
|
||||
**Example:**
|
||||
```shell
|
||||
touch agents/myAgent.md
|
||||
touch .opencode/prompts/agents/myAgent.txt
|
||||
```bash
|
||||
/update-docs
|
||||
```
|
||||
|
||||
## Testing Patterns
|
||||
|
||||
- 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
|
||||
});
|
||||
```
|
||||
- **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');
|
||||
});
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| 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 |
|
||||
| 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 |
|
||||
```
|
||||
|
||||
@@ -11,5 +11,5 @@
|
||||
".claude/commands/refactoring.md",
|
||||
".claude/commands/add-or-update-skill.md"
|
||||
],
|
||||
"updatedAt": "2026-04-01T23:05:46.781Z"
|
||||
"updatedAt": "2026-04-01T22:57:31.655Z"
|
||||
}
|
||||
@@ -59,8 +59,6 @@ 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
|
||||
@@ -99,6 +97,3 @@ 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,43 +20,16 @@ function readJsonObject(filePath, label) {
|
||||
return parsed;
|
||||
}
|
||||
|
||||
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) {
|
||||
function buildLegacyHookSignature(entry) {
|
||||
if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const normalizedEntry = replacePluginRootPlaceholders(entry, pluginRoot);
|
||||
|
||||
if (typeof normalizedEntry.matcher !== 'string' || !Array.isArray(normalizedEntry.hooks)) {
|
||||
if (typeof entry.matcher !== 'string' || !Array.isArray(entry.hooks)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const hookSignature = normalizedEntry.hooks.map(hook => JSON.stringify({
|
||||
const hookSignature = entry.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,
|
||||
@@ -64,35 +37,33 @@ function buildLegacyHookSignature(entry, pluginRoot) {
|
||||
}));
|
||||
|
||||
return JSON.stringify({
|
||||
matcher: normalizedEntry.matcher,
|
||||
matcher: entry.matcher,
|
||||
hooks: hookSignature,
|
||||
});
|
||||
}
|
||||
|
||||
function getHookEntryAliases(entry, pluginRoot) {
|
||||
function getHookEntryAliases(entry) {
|
||||
const aliases = [];
|
||||
|
||||
if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
|
||||
return aliases;
|
||||
}
|
||||
|
||||
const normalizedEntry = replacePluginRootPlaceholders(entry, pluginRoot);
|
||||
|
||||
if (typeof normalizedEntry.id === 'string' && normalizedEntry.id.trim().length > 0) {
|
||||
aliases.push(`id:${normalizedEntry.id.trim()}`);
|
||||
if (typeof entry.id === 'string' && entry.id.trim().length > 0) {
|
||||
aliases.push(`id:${entry.id.trim()}`);
|
||||
}
|
||||
|
||||
const legacySignature = buildLegacyHookSignature(normalizedEntry, pluginRoot);
|
||||
const legacySignature = buildLegacyHookSignature(entry);
|
||||
if (legacySignature) {
|
||||
aliases.push(`legacy:${legacySignature}`);
|
||||
}
|
||||
|
||||
aliases.push(`json:${JSON.stringify(normalizedEntry)}`);
|
||||
aliases.push(`json:${JSON.stringify(entry)}`);
|
||||
|
||||
return aliases;
|
||||
}
|
||||
|
||||
function mergeHookEntries(existingEntries, incomingEntries, pluginRoot) {
|
||||
function mergeHookEntries(existingEntries, incomingEntries) {
|
||||
const mergedEntries = [];
|
||||
const seenEntries = new Set();
|
||||
|
||||
@@ -105,7 +76,7 @@ function mergeHookEntries(existingEntries, incomingEntries, pluginRoot) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const aliases = getHookEntryAliases(entry, pluginRoot);
|
||||
const aliases = getHookEntryAliases(entry);
|
||||
if (aliases.some(alias => seenEntries.has(alias))) {
|
||||
continue;
|
||||
}
|
||||
@@ -113,7 +84,7 @@ function mergeHookEntries(existingEntries, incomingEntries, pluginRoot) {
|
||||
for (const alias of aliases) {
|
||||
seenEntries.add(alias);
|
||||
}
|
||||
mergedEntries.push(replacePluginRootPlaceholders(entry, pluginRoot));
|
||||
mergedEntries.push(entry);
|
||||
}
|
||||
|
||||
return mergedEntries;
|
||||
@@ -129,7 +100,6 @@ 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)) {
|
||||
@@ -137,7 +107,7 @@ function buildMergedSettings(plan) {
|
||||
}
|
||||
|
||||
const hooksConfig = readJsonObject(hooksSourcePath, 'hooks config');
|
||||
const incomingHooks = replacePluginRootPlaceholders(hooksConfig.hooks, pluginRoot);
|
||||
const incomingHooks = hooksConfig.hooks;
|
||||
if (!incomingHooks || typeof incomingHooks !== 'object' || Array.isArray(incomingHooks)) {
|
||||
throw new Error(`Invalid hooks config at ${hooksSourcePath}: expected "hooks" to be a JSON object`);
|
||||
}
|
||||
@@ -156,7 +126,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, pluginRoot);
|
||||
mergedHooks[eventName] = mergeHookEntries(currentEntries, nextEntries);
|
||||
}
|
||||
|
||||
const mergedSettings = {
|
||||
@@ -167,11 +137,6 @@ function buildMergedSettings(plan) {
|
||||
return {
|
||||
settingsPath,
|
||||
mergedSettings,
|
||||
hooksDestinationPath,
|
||||
resolvedHooksConfig: {
|
||||
...hooksConfig,
|
||||
hooks: incomingHooks,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
@@ -184,12 +149,6 @@ 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,23 +106,7 @@ extract_toml_value() {
|
||||
|
||||
extract_context7_key() {
|
||||
local file="$1"
|
||||
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
|
||||
grep -oP -- '--key",[[:space:]]*"\K[^"]+' "$file" | head -n 1 || true
|
||||
}
|
||||
|
||||
generate_prompt_file() {
|
||||
|
||||
@@ -353,45 +353,6 @@ 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,15 +74,6 @@ 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