Skip to content

Commit 9b57dc2

Browse files
nmccreadynmccready
authored
Merge pull request #6 from brickhouse-tech/feat/inheritance
feat: add inheritance convention support
2 parents fe3ccaa + 673131e commit 9b57dc2

File tree

11 files changed

+683
-6
lines changed

11 files changed

+683
-6
lines changed

‎.github/workflows/tests.yml‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,13 @@ on:
99
- '.github/workflows/**'
1010
jobs:
1111
test:
12-
strategy:
13-
matrix:
14-
node-version: ['20.x', '22.x', '24.x']
1512
runs-on: ubuntu-latest
1613
steps:
1714
- uses: actions/checkout@v4
18-
- name: Use Node.js ${{ matrix.node-version }}
15+
- name: Use Node.js 22.x
1916
uses: actions/setup-node@v4
2017
with:
21-
node-version: ${{ matrix.node-version }}
22-
# cache: "npm" # needs lockfile if enabled
18+
node-version: '22.x'
2319

2420
- run: npm install
2521
- run: npm run lint

‎README.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,9 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
6363
| `watch` | Watch `.agents/` for changes and auto-regenerate `AGENTS.md` |
6464
| `import <url>` | Import a rule/skill/workflow from a URL |
6565
| `hook` | Install a pre-commit git hook for auto-sync |
66+
| `inherit <label> <path>` | Add an inheritance link to AGENTS.md |
67+
| `inherit --list` | List current inheritance links |
68+
| `inherit --remove <label>` | Remove an inheritance link by label |
6669
| `status` | Show the current sync status of all targets and symlinks |
6770
| `add <type> <name>` | Add a new rule, skill, or workflow from a template (type is `rule`, `skill`, or `workflow`) |
6871
| `index` | Regenerate `AGENTS.md` by scanning the contents of `.agents/` |
@@ -79,6 +82,150 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
7982
| `--dry-run` | Show what would be done without making changes |
8083
| `--force` | Overwrite existing files and symlinks |
8184

85+
## Inheritance
86+
87+
Projects can inherit agent rules from parent directories (org, team, global) using a convention-based approach. This enables hierarchical rule sharing without duplicating files.
88+
89+
### How It Works
90+
91+
Add an `## Inherits` section to your project's `AGENTS.md` that links to parent-level agent configs:
92+
93+
```markdown
94+
## Inherits
95+
- [global](../../AGENTS.md)
96+
- [team](../AGENTS.md)
97+
```
98+
99+
AI agents (Claude, Codex, etc.) follow markdown links natively — when they read your project's `AGENTS.md`, they'll traverse the inheritance chain and apply rules from all levels.
100+
101+
### Hierarchy Example
102+
103+
```
104+
~/code/ # Global: security norms, universal rules
105+
├── .agents/
106+
├── AGENTS.md
107+
└── org/ # Org-level: coding standards, shared workflows
108+
├── .agents/
109+
├── AGENTS.md
110+
└── team/ # Team-level: language-specific rules
111+
├── .agents/
112+
├── AGENTS.md
113+
└── project/ # Project: project-specific rules + inherits
114+
├── .agents/
115+
└── AGENTS.md → ## Inherits links to team, org, global
116+
```
117+
118+
**Inheritance is upward-only.** A project declares what it inherits from. Parent directories don't need to know about their children — when an agent works at the org level, it already has access to org-level rules.
119+
120+
### Managing Inheritance
121+
122+
```bash
123+
# Add an inheritance link
124+
sync-agents inherit global ../../AGENTS.md
125+
sync-agents inherit team ../AGENTS.md
126+
127+
# List current inheritance links
128+
sync-agents inherit --list
129+
130+
# Remove an inheritance link
131+
sync-agents inherit --remove global
132+
```
133+
134+
The `## Inherits` section is preserved across `sync-agents index` regenerations.
135+
136+
### Full Example
137+
138+
Set up a three-level hierarchy: global rules → org standards → project config.
139+
140+
```bash
141+
# 1. Create global rules (e.g. ~/code/.agents/)
142+
cd ~/code
143+
sync-agents init
144+
sync-agents add rule security
145+
cat > .agents/rules/security.md << 'EOF'
146+
---
147+
trigger: always_on
148+
---
149+
# Security
150+
- Never commit secrets or API keys
151+
- Validate all external input
152+
- Use parameterized queries for database access
153+
EOF
154+
155+
# 2. Create org-level rules (e.g. ~/code/myorg/.agents/)
156+
cd ~/code/myorg
157+
sync-agents init
158+
sync-agents add rule go-standards
159+
cat > .agents/rules/go-standards.md << 'EOF'
160+
---
161+
trigger: always_on
162+
---
163+
# Go Standards
164+
- Use `gofmt` and `golangci-lint` on all Go files
165+
- Prefer table-driven tests
166+
- Export only what consumers need
167+
EOF
168+
169+
# 3. Create project with inheritance
170+
cd ~/code/myorg/api-service
171+
sync-agents init
172+
sync-agents add rule api-conventions
173+
174+
# Link to parent levels
175+
sync-agents inherit org ../AGENTS.md
176+
sync-agents inherit global ../../AGENTS.md
177+
178+
# Sync to agent directories
179+
sync-agents sync
180+
```
181+
182+
The project's `AGENTS.md` now looks like:
183+
184+
```markdown
185+
## Inherits
186+
- [org](../AGENTS.md)
187+
- [global](../../AGENTS.md)
188+
189+
## Rules
190+
- [api-conventions](.agents/rules/api-conventions.md)
191+
192+
## Skills
193+
_No skills defined yet._
194+
195+
## Workflows
196+
_No workflows defined yet._
197+
```
198+
199+
When an AI agent reads this file, it follows the `## Inherits` links and applies rules from all three levels — project-specific API conventions, org-wide Go standards, and global security rules.
200+
201+
### Verifying Inheritance
202+
203+
```bash
204+
# Check what's inherited
205+
sync-agents inherit --list
206+
# Output:
207+
# - [org](../AGENTS.md)
208+
# - [global](../../AGENTS.md)
209+
210+
# Remove a link if no longer needed
211+
sync-agents inherit --remove global
212+
213+
# Re-add with a different path
214+
sync-agents inherit global ../../AGENTS.md
215+
```
216+
217+
## Examples
218+
219+
The [`examples/`](examples/) directory contains ready-to-use rules, skills, and workflows. Import them directly:
220+
221+
```bash
222+
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/rules/no-secrets.md
223+
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/skills/code-review.md
224+
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/workflows/pr-checklist.md
225+
```
226+
227+
See [examples/README.md](examples/README.md) for the full list.
228+
82229
## Usage
83230

84231
```bash

‎examples/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Examples
2+
3+
Ready-to-use rules, skills, and workflows for `sync-agents`.
4+
5+
## Quick Import
6+
7+
```bash
8+
# Import directly from GitHub
9+
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/rules/no-secrets.md
10+
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/skills/code-review.md
11+
sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/workflows/pr-checklist.md
12+
```
13+
14+
## Contents
15+
16+
### Rules
17+
| File | Description |
18+
|---|---|
19+
| [no-secrets](rules/no-secrets.md) | Prevent committing API keys, tokens, and credentials |
20+
| [commit-conventions](rules/commit-conventions.md) | Enforce Conventional Commits format |
21+
| [no-force-push](rules/no-force-push.md) | Protect shared branches from history rewrites |
22+
23+
### Skills
24+
| File | Description |
25+
|---|---|
26+
| [code-review](skills/code-review.md) | Systematic PR review process |
27+
| [debugging](skills/debugging.md) | Structured approach to diagnosing issues |
28+
29+
### Workflows
30+
| File | Description |
31+
|---|---|
32+
| [pr-checklist](workflows/pr-checklist.md) | Pre-flight checklist before opening a PR |
33+
34+
## Contributing
35+
36+
Add your own examples via PR! Follow the templates in `src/md/` for consistent formatting.

‎examples/rules/commit-conventions.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Commit Conventions
6+
7+
All commits must follow [Conventional Commits](https://www.conventionalcommits.org/).
8+
9+
## Format
10+
11+
```
12+
<type>(<scope>): <description>
13+
14+
[optional body]
15+
16+
[optional footer(s)]
17+
```
18+
19+
## Types
20+
21+
| Type | When to use |
22+
|---|---|
23+
| `feat` | New feature or capability |
24+
| `fix` | Bug fix |
25+
| `docs` | Documentation only |
26+
| `style` | Formatting, whitespace (no logic change) |
27+
| `refactor` | Code restructuring (no feature or fix) |
28+
| `perf` | Performance improvement |
29+
| `test` | Adding or updating tests |
30+
| `build` | Build system or dependencies |
31+
| `ci` | CI/CD configuration |
32+
| `chore` | Maintenance tasks |
33+
34+
## Rules
35+
36+
- Subject line: imperative mood, lowercase, no period, max 72 characters
37+
- Body: wrap at 72 characters, explain *what* and *why* (not *how*)
38+
- Breaking changes: add `BREAKING CHANGE:` in footer or `!` after type
39+
- Reference issues: `Fixes #123` or `Closes #456` in footer
40+
- One logical change per commit — don't mix features with refactors

‎examples/rules/no-force-push.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# No Force Push
6+
7+
Protect shared branches from history rewrites.
8+
9+
## Rules
10+
11+
- Never `git push --force` to `main`, `master`, `develop`, or any release branch
12+
- Use `--force-with-lease` on feature branches only, and only when you own the branch
13+
- If a rebase is needed on a shared branch, coordinate with the team first
14+
- Prefer merge commits or squash merges over rebasing shared history
15+
- If you accidentally force-pushed a shared branch, notify the team immediately and restore from reflog

‎examples/rules/no-secrets.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# No Secrets
6+
7+
Never commit secrets, credentials, or sensitive values to the repository.
8+
9+
## Rules
10+
11+
- Do not hardcode API keys, tokens, passwords, or connection strings in source code
12+
- Do not commit `.env`, `.envrc`, or any file containing secrets
13+
- Use environment variables or a secrets manager (1Password, Vault, AWS Secrets Manager) for all credentials
14+
- If a secret is accidentally committed, rotate it immediately — git history is permanent
15+
- Use placeholder values in examples and documentation (e.g. `YOUR_API_KEY_HERE`)
16+
- Ensure `.gitignore` includes: `.env`, `.env.*`, `*.pem`, `*.key`, `credentials.json`
17+
18+
## Detection
19+
20+
Flag any of these patterns in code review:
21+
- Strings matching `sk-`, `ghp_`, `gho_`, `AKIA`, `xox`, `Bearer ` followed by a long alphanumeric string
22+
- Base64-encoded blobs assigned to variables named `key`, `secret`, `token`, `password`, `credential`
23+
- Hardcoded URLs containing `@` (embedded credentials)

‎examples/skills/code-review.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Code Review
6+
7+
Systematic approach to reviewing pull requests.
8+
9+
## Process
10+
11+
1. **Understand context** — Read the PR description, linked issues, and related docs before looking at code
12+
2. **Check scope** — Does the PR do one thing? Flag scope creep early
13+
3. **Read tests first** — Tests reveal intent; if there are no tests, that's the first comment
14+
4. **Review logic** — Walk through the code path as if you're the runtime
15+
5. **Check edge cases** — Empty inputs, nulls, large datasets, concurrent access, error paths
16+
6. **Verify naming** — Variables, functions, and files should be self-documenting
17+
7. **Security scan** — Look for injection, auth bypass, data exposure, unsafe deserialization
18+
8. **Performance** — N+1 queries, unbounded loops, missing pagination, large allocations
19+
20+
## Comment Style
21+
22+
- **Blocking:** Prefix with `[blocking]` — must fix before merge
23+
- **Suggestion:** Prefix with `[nit]` or `[suggestion]` — take it or leave it
24+
- **Question:** Prefix with `[question]` — clarify intent, not a change request
25+
- Be specific: link to the line, show the fix, explain why
26+
27+
## Approve When
28+
29+
- All blocking comments are resolved
30+
- Tests pass and cover the change
31+
- No security concerns
32+
- Code is readable by someone who didn't write it

‎examples/skills/debugging.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
trigger: always_on
3+
---
4+
5+
# Debugging
6+
7+
Structured approach to diagnosing and resolving issues.
8+
9+
## Process
10+
11+
1. **Reproduce** — Can you trigger the bug reliably? Define exact steps, inputs, and environment
12+
2. **Isolate** — Narrow the scope. Binary search: comment out half the code, which half breaks?
13+
3. **Read the error** — Stack traces, logs, error codes. The answer is often in the message
14+
4. **Check recent changes** — `git log --oneline -20` and `git diff` against last known working state
15+
5. **Form a hypothesis** — State what you think is wrong *before* changing code
16+
6. **Test the hypothesis** — One change at a time. If it didn't fix it, revert before trying the next thing
17+
7. **Verify the fix** — Reproduce the original steps. Confirm the bug is gone. Check for regressions
18+
8. **Document** — Add a test that would have caught it. Update comments if the code was misleading
19+
20+
## Anti-Patterns
21+
22+
- Shotgun debugging: changing multiple things at once
23+
- Print-statement overload without a hypothesis
24+
- Fixing symptoms instead of root causes
25+
- "It works on my machine" without checking environment differences
26+
- Ignoring warnings and deprecation notices
27+
28+
## Tools
29+
30+
- **Logs:** Check application logs, system logs, browser console
31+
- **Debugger:** Step through with breakpoints rather than guessing
32+
- **Git bisect:** `git bisect start` → `git bisect bad` → `git bisect good <sha>` to find the breaking commit
33+
- **Minimal reproduction:** Strip the problem to the smallest possible case

0 commit comments

Comments
 (0)