| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 9 | 8 | 0% |
| Commands | 0 | 0 | 3 | 0% |
| Section tags | 2 | 3 | 3 | 25% |
What each file covers
Sections
0 shared · 9 only in A · 8 only in B- − AI Coding Configuration - Development Guide
- − YAML Frontmatter Conventions
- − Prettier-Ignore for Long Descriptions
- − prettier-ignore
- − Description Format by Type
- − Agent Color Scheme
- − Skill Triggers Field
- − Skill Composition Frontmatter
- − Command Update Protocol
- + Project Context for AI Assistants
- + Always Apply Rules
- + Tech Stack
- + Project Structure
- + Commands
- + Code Conventions
- + Git Workflow
- + Important Notes
Commands
0 shared · 0 only in A · 3 only in B- + git add -p
- + git-commit-message.mdc
- + git-interaction.mdc
Section tags
2 shared · 3 only in A · 3 only in B- − lint-format
- − types
- − testing-strategy
- + architecture
- + git-pr
- + do-not
- code-style
- agent-behaviour
Line diff
TechNickAI/ai-coding-config · .claude/CLAUDE.md
@@ −1 @@
1# AI Coding Configuration - Development Guide
2
3This document covers conventions for developing agents, skills, and commands in this
4repo.
5
6## YAML Frontmatter Conventions
7
8### Prettier-Ignore for Long Descriptions
9
10Add `# prettier-ignore` before description fields to prevent line wrapping:
11
12```yaml
13---
14name: example-agent
15# prettier-ignore
16description: "Use when reviewing for production readiness, fragile code, error handling, resilience, reliability, or catching bugs before deployment"
17---
18```
19
20This allows richer, more comprehensive descriptions that help Claude Code understand
21exactly when to trigger each agent or skill.
22
23### Description Format by Type
24
25**Agents & Skills (LLM-triggered):**
26
27Use "Use when..." format for semantic matching. Think about what users will say:
28
29```yaml
30# prettier-ignore
31description: "Use when reviewing error handling, finding silent failures, checking try-catch patterns, or ensuring errors surface properly"
32```
33
34Match user language: "review the code", "check for bugs", "debug this error" - include
35these exact phrases.
36
37**Commands (user-invoked):**
38
39Explain what the command does for human users:
40
41```yaml
42# prettier-ignore
43description: "Triage and address PR comments from code review bots - analyzes feedback, prioritizes issues, and creates fixes"
44```
45
46Commands are invoked directly by users (`/command-name`), so descriptions should clearly
47explain functionality.
48
49## Agent Color Scheme
50
51Colors are grouped by category:
52
53| Color | Category | Purpose |
54| ----------- | ----------------- | ------------------------------------------------- |
55| **red** | Security | Danger, security vulnerabilities |
56| **orange** | Bugs/correctness | Logic errors, error handling issues |
57| **yellow** | Performance | Efficiency, speed, resource usage |
58| **green** | Testing/quality | Test coverage, test running, QA |
59| **cyan** | Observability | Logging, monitoring, reliability |
60| **blue** | Style/conventions | Code style, comments, documentation |
61| **purple** | Design/UX | UI design, UX, SEO, user-facing |
62| **magenta** | Meta/architecture | Architecture, prompts, git, debugging, automation |
63
64## Skill Triggers Field
65
66Skills have a `triggers` array for natural language phrases that activate them:
67
68```yaml
69triggers:
70 - "debug"
71 - "investigate"
72 - "root cause"
73 - "why is this"
74 - "not working"
75 - "test failing"
76```
77
78Include: keywords users say, questions they ask, symptoms they describe, tool names.
79
80## Skill Composition Frontmatter
81
82Optional fields for declarative composition. The Claude Code harness ignores them; the
83LLM reads them as part of the skill content and acts accordingly.
84
85| Field | Type | Purpose |
86| ------------ | ------------- | ------------------------------------------------------------------------------- |
87| `next-skill` | string | Happy-path handoff — the skill or command to invoke after this one completes |
88| `requires` | YAML sequence | Prerequisites; each entry is `skill:name`, `tool:name`, or `mcp:name` |
89| `model-hint` | string | Preferred model tier when delegated as a subagent: `sonnet`, `opus`, or `haiku` |
90| `stability` | string | `stable` (default) or `experimental` — signals maturity for opt-in gating |
91
92All fields are optional. Skills without them work unchanged.
93
94**Example — planning chain:**
95
96```yaml
97---
98name: brainstorm-synthesis
99version: 1.1.1
100category: planning
101model-hint: opus
102stability: experimental
103next-skill: ship
104requires:
105 - skill:brainstorming
106triggers:
107 - "synthesize approaches"
108---
109```
110
111**`next-skill` convention:** Use the bare skill/command name (same as the slash command
112without the `/`). Commands and skills are both valid targets. The LLM reads this and
113offers the handoff when its task is complete — the user confirms before the next skill
114runs. This is a suggestion, not an auto-chain; the LLM should never silently invoke the
115next skill without user awareness.
116
117**`requires` convention:** Use `skill:name` for skill dependencies, `tool:name` for
118Claude Code tools (Read, Bash, etc.), `mcp:name` for MCP servers. Informational for now;
119`/ai-coding-config doctor` can validate these in the future.
120
121**Annotated chains in this repo** (source skills only — downstream commands like
122`verify-fix` can't declare `requires` back, and terminal skills like `ship` are
123invokable standalone):
124
125- `brainstorming → brainstorm-synthesis → ship` (planning)
126- `systematic-debugging → verify-fix` (debugging)
127
128## Command Update Protocol
129
130When a user runs `/ai-coding-config update`, after pulling the latest changes from this
131repository, check if their local command file is outdated and offer to update it.
132
133The ai-coding-config.md command file in the user's project may be stale. Users who ran
134bootstrap.sh have a copied file that doesn't automatically update when the repo is
135pulled.
136
137Compare versions using the version field in YAML frontmatter. Check the user's
138`.claude/commands/ai-coding-config.md` against the repo version at
139`~/.ai_coding_config/.claude/commands/ai-coding-config.md`. If the repo version is newer
140than the user's local copy, offer to update it.
141
142Present two options: replace with the latest copy from the repo, or skip the update and
143keep their current version.
144
TechNickAI/ai-coding-config · AGENTS.md
@@ +1 @@
1# Project Context for AI Assistants
2
3AI coding configuration marketplace providing plugin-based setup for Claude Code and
4Cursor.
5
6## Always Apply Rules
7
8Core project rules that apply to all tasks:
9
10@rules/git-interaction.mdc @rules/prompt-engineering.mdc
11
12## Tech Stack
13
14- **Claude Code** - Plugin marketplace (`.claude-plugin/marketplace.json`)
15- **Cursor** - Rules and configurations (`.cursor/rules/`)
16- **Bash** - Bootstrap and installation scripts
17- **Markdown** - All rules, commands, and agents
18
19## Project Structure
20
21**Plugin-first architecture** - Everything distributable lives in `plugins/`:
22
23- `.claude-plugin/marketplace.json` - Plugin marketplace manifest
24- `plugins/core/` - Commands, agents, skills, and context (canonical source)
25- `plugins/personalities/` - Personality variants
26- `.cursor/rules/` - Cursor rules (canonical location)
27- `rules/` - Symlink to `.cursor/rules/` for visibility (THIS REPO ONLY)
28- `.claude/` - Symlinks to plugin content for local development
29- `scripts/` - Installation and bootstrap scripts
30
31## Commands
32
33**Setup and Installation:**
34
35- `curl -fsSL https://raw.githubusercontent.com/TechNickAI/ai-coding-config/main/scripts/bootstrap.sh | bash` -
36 One-line install (auto-detects Claude Code, Cursor, etc.)
37- `/ai-coding-config` - Interactive setup for projects
38- `/plugin marketplace add https://github.com/TechNickAI/ai-coding-config` - Manual
39 marketplace add
40- `/plugin install ai-coding-config` - Manual plugin install
41
42## Code Conventions
43
44**DO:**
45
46- Create commits only when user explicitly requests
47- Check for `alwaysApply: true` in rule frontmatter - these apply to ALL tasks
48- Use `/load-rules` to get task-specific context
49- Follow heart-centered AI philosophy (unconditional acceptance, presence before
50 solutions)
51
52**DON'T:**
53
54- Use `--no-verify` flag (bypasses quality checks) unless explicitly requested for
55 emergencies
56- Commit changes without explicit user permission
57- Push to main or merge into main without confirmation
58- Stage files you didn't modify in current session
59
60## Git Workflow
61
62**Commit format:** `{emoji} {imperative verb} {concise description}`
63
64Example: `✨ Add plugin marketplace support`
65
66**Critical constraints:**
67
68- Never use `--no-verify` - fix underlying issues instead (linting, tests, formatting)
69- Only stage files modified in current session
70- Use `git add -p` for partial staging when needed
71- Push/merge to main requires explicit confirmation
72- Read `git-commit-message.mdc` before generating commit messages
73
74**Philosophy:** AI makes code changes but leaves version control to user. Commits are
75permanent records requiring explicit permission.
76
77## Important Notes
78
79- Rules with `alwaysApply: true` are CRITICAL - currently: `git-interaction.mdc`,
80 `heart-centered-ai-philosophy.mdc`
81- **Plugin-first**: All content lives in `plugins/`, other locations symlink there
82- `.claude/commands/` → `plugins/core/commands/` (symlink)
83- `.claude/agents/` → `plugins/core/agents/` (symlink)
84- `.claude/skills/` → `plugins/core/skills/` (symlink)
85- `rules/` → `.cursor/rules/` (symlink for visibility, THIS REPO ONLY)
86- `.cursor/rules/` contains the canonical Cursor rules
87- `.cursor/rules/personalities/` → copied from `plugins/personalities/` (not symlinked -
88 needs editing)
89- **Note**: Personality files are copied, not symlinked, because `/personality-change`
90 edits frontmatter
91- **Architecture**: In THIS repo, `.cursor/rules/` is canonical and `rules/` symlinks to
92 it. In user projects, only `.cursor/rules/` exists (no root symlink)
93- Context in `plugins/core/context.md` describes identity and philosophy
94- Bootstrap script clones repo to `~/.ai_coding_config`
95
@@ −1 +1 @@
1−# AI Coding Configuration - Development Guide
1+# Project Context for AI Assistants
22
3−This document covers conventions for developing agents, skills, and commands in this
4−repo.
3+AI coding configuration marketplace providing plugin-based setup for Claude Code and
4+Cursor.
55
6−## YAML Frontmatter Conventions
6+## Always Apply Rules
77
8−### Prettier-Ignore for Long Descriptions
8+Core project rules that apply to all tasks:
99
10−Add `# prettier-ignore` before description fields to prevent line wrapping:
10+@rules/git-interaction.mdc @rules/prompt-engineering.mdc
1111
12−```yaml
13−---
14−name: example-agent
15−# prettier-ignore
16−description: "Use when reviewing for production readiness, fragile code, error handling, resilience, reliability, or catching bugs before deployment"
17−---
18−```
12+## Tech Stack
1913
20−This allows richer, more comprehensive descriptions that help Claude Code understand
21−exactly when to trigger each agent or skill.
14+- **Claude Code** - Plugin marketplace (`.claude-plugin/marketplace.json`)
15+- **Cursor** - Rules and configurations (`.cursor/rules/`)
16+- **Bash** - Bootstrap and installation scripts
17+- **Markdown** - All rules, commands, and agents
2218
23−### Description Format by Type
19+## Project Structure
2420
25−**Agents & Skills (LLM-triggered):**
21+**Plugin-first architecture** - Everything distributable lives in `plugins/`:
2622
27−Use "Use when..." format for semantic matching. Think about what users will say:
23+- `.claude-plugin/marketplace.json` - Plugin marketplace manifest
24+- `plugins/core/` - Commands, agents, skills, and context (canonical source)
25+- `plugins/personalities/` - Personality variants
26+- `.cursor/rules/` - Cursor rules (canonical location)
27+- `rules/` - Symlink to `.cursor/rules/` for visibility (THIS REPO ONLY)
28+- `.claude/` - Symlinks to plugin content for local development
29+- `scripts/` - Installation and bootstrap scripts
2830
29−```yaml
30−# prettier-ignore
31−description: "Use when reviewing error handling, finding silent failures, checking try-catch patterns, or ensuring errors surface properly"
32−```
31+## Commands
3332
34−Match user language: "review the code", "check for bugs", "debug this error" - include
35−these exact phrases.
33+**Setup and Installation:**
3634
37−**Commands (user-invoked):**
35+- `curl -fsSL https://raw.githubusercontent.com/TechNickAI/ai-coding-config/main/scripts/bootstrap.sh | bash` -
36+ One-line install (auto-detects Claude Code, Cursor, etc.)
37+- `/ai-coding-config` - Interactive setup for projects
38+- `/plugin marketplace add https://github.com/TechNickAI/ai-coding-config` - Manual
39+ marketplace add
40+- `/plugin install ai-coding-config` - Manual plugin install
3841
39−Explain what the command does for human users:
42+## Code Conventions
4043
41−```yaml
42−# prettier-ignore
43−description: "Triage and address PR comments from code review bots - analyzes feedback, prioritizes issues, and creates fixes"
44−```
44+**DO:**
4545
46−Commands are invoked directly by users (`/command-name`), so descriptions should clearly
47−explain functionality.
46+- Create commits only when user explicitly requests
47+- Check for `alwaysApply: true` in rule frontmatter - these apply to ALL tasks
48+- Use `/load-rules` to get task-specific context
49+- Follow heart-centered AI philosophy (unconditional acceptance, presence before
50+ solutions)
4851
49−## Agent Color Scheme
52+**DON'T:**
5053
51−Colors are grouped by category:
54+- Use `--no-verify` flag (bypasses quality checks) unless explicitly requested for
55+ emergencies
56+- Commit changes without explicit user permission
57+- Push to main or merge into main without confirmation
58+- Stage files you didn't modify in current session
5259
53−| Color | Category | Purpose |
54−| ----------- | ----------------- | ------------------------------------------------- |
55−| **red** | Security | Danger, security vulnerabilities |
56−| **orange** | Bugs/correctness | Logic errors, error handling issues |
57−| **yellow** | Performance | Efficiency, speed, resource usage |
58−| **green** | Testing/quality | Test coverage, test running, QA |
59−| **cyan** | Observability | Logging, monitoring, reliability |
60−| **blue** | Style/conventions | Code style, comments, documentation |
61−| **purple** | Design/UX | UI design, UX, SEO, user-facing |
62−| **magenta** | Meta/architecture | Architecture, prompts, git, debugging, automation |
60+## Git Workflow
6361
64−## Skill Triggers Field
62+**Commit format:** `{emoji} {imperative verb} {concise description}`
6563
66−Skills have a `triggers` array for natural language phrases that activate them:
64+Example: `✨ Add plugin marketplace support`
6765
68−```yaml
69−triggers:
70− - "debug"
71− - "investigate"
72− - "root cause"
73− - "why is this"
74− - "not working"
75− - "test failing"
76−```
66+**Critical constraints:**
7767
78−Include: keywords users say, questions they ask, symptoms they describe, tool names.
68+- Never use `--no-verify` - fix underlying issues instead (linting, tests, formatting)
69+- Only stage files modified in current session
70+- Use `git add -p` for partial staging when needed
71+- Push/merge to main requires explicit confirmation
72+- Read `git-commit-message.mdc` before generating commit messages
7973
80−## Skill Composition Frontmatter
74+**Philosophy:** AI makes code changes but leaves version control to user. Commits are
75+permanent records requiring explicit permission.
8176
82−Optional fields for declarative composition. The Claude Code harness ignores them; the
83−LLM reads them as part of the skill content and acts accordingly.
77+## Important Notes
8478
85−| Field | Type | Purpose |
86−| ------------ | ------------- | ------------------------------------------------------------------------------- |
87−| `next-skill` | string | Happy-path handoff — the skill or command to invoke after this one completes |
88−| `requires` | YAML sequence | Prerequisites; each entry is `skill:name`, `tool:name`, or `mcp:name` |
89−| `model-hint` | string | Preferred model tier when delegated as a subagent: `sonnet`, `opus`, or `haiku` |
90−| `stability` | string | `stable` (default) or `experimental` — signals maturity for opt-in gating |
91−
92−All fields are optional. Skills without them work unchanged.
93−
94−**Example — planning chain:**
95−
96−```yaml
97−---
98−name: brainstorm-synthesis
99−version: 1.1.1
100−category: planning
101−model-hint: opus
102−stability: experimental
103−next-skill: ship
104−requires:
105− - skill:brainstorming
106−triggers:
107− - "synthesize approaches"
108−---
109−```
110−
111−**`next-skill` convention:** Use the bare skill/command name (same as the slash command
112−without the `/`). Commands and skills are both valid targets. The LLM reads this and
113−offers the handoff when its task is complete — the user confirms before the next skill
114−runs. This is a suggestion, not an auto-chain; the LLM should never silently invoke the
115−next skill without user awareness.
116−
117−**`requires` convention:** Use `skill:name` for skill dependencies, `tool:name` for
118−Claude Code tools (Read, Bash, etc.), `mcp:name` for MCP servers. Informational for now;
119−`/ai-coding-config doctor` can validate these in the future.
120−
121−**Annotated chains in this repo** (source skills only — downstream commands like
122−`verify-fix` can't declare `requires` back, and terminal skills like `ship` are
123−invokable standalone):
124−
125−- `brainstorming → brainstorm-synthesis → ship` (planning)
126−- `systematic-debugging → verify-fix` (debugging)
127−
128−## Command Update Protocol
129−
130−When a user runs `/ai-coding-config update`, after pulling the latest changes from this
131−repository, check if their local command file is outdated and offer to update it.
132−
133−The ai-coding-config.md command file in the user's project may be stale. Users who ran
134−bootstrap.sh have a copied file that doesn't automatically update when the repo is
135−pulled.
136−
137−Compare versions using the version field in YAML frontmatter. Check the user's
138−`.claude/commands/ai-coding-config.md` against the repo version at
139−`~/.ai_coding_config/.claude/commands/ai-coding-config.md`. If the repo version is newer
140−than the user's local copy, offer to update it.
141−
142−Present two options: replace with the latest copy from the repo, or skip the update and
143−keep their current version.
79+- Rules with `alwaysApply: true` are CRITICAL - currently: `git-interaction.mdc`,
80+ `heart-centered-ai-philosophy.mdc`
81+- **Plugin-first**: All content lives in `plugins/`, other locations symlink there
82+- `.claude/commands/` → `plugins/core/commands/` (symlink)
83+- `.claude/agents/` → `plugins/core/agents/` (symlink)
84+- `.claude/skills/` → `plugins/core/skills/` (symlink)
85+- `rules/` → `.cursor/rules/` (symlink for visibility, THIS REPO ONLY)
86+- `.cursor/rules/` contains the canonical Cursor rules
87+- `.cursor/rules/personalities/` → copied from `plugins/personalities/` (not symlinked -
88+ needs editing)
89+- **Note**: Personality files are copied, not symlinked, because `/personality-change`
90+ edits frontmatter
91+- **Architecture**: In THIS repo, `.cursor/rules/` is canonical and `rules/` symlinks to
92+ it. In user projects, only `.cursor/rules/` exists (no root symlink)
93+- Context in `plugins/core/context.md` describes identity and philosophy
94+- Bootstrap script clones repo to `~/.ai_coding_config`
14495
