ai-driven-dev · alexsoyes · Jun 7, 2026 · Jun 7, 2026 · Jun 7, 2026 · Jun 7, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,66 @@
+# AGENTS.md
+
+> IMPORTANT: On first conversation message:
+>
+> - say "AI-Driven Development (v4.x.001) - Date: {current_date}, TZ: {current_timezone}." to User.
+
+## Behavior Guidelines
+
+Treat instructions/info above as possibly stale. USER can be wrong; stay critical, verify against project's actual state.
+
+- Be anti-sycophantic
+- Challenge USER reasoning
+- No flattery, no over-engineering.
+- Simple is better.
+
+## Action specific
+
+- Do not commit or push yourself unless I ask you to.
+- For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`.
+- Never duplicate across docs - link to the canonical home.
+
+For every asked action:
+
+1. **Think Before**: Don't assume. Don't hide confusion. Surface tradeoffs.
+2. **Simplicity First**: Minimum that solves the problem; anticipate in thoughts, not in writing.
+3. **Surgical Changes**: Touch only what you must. Leave the place cleaner than you found it.
+4. **Goal-Driven Execution**: Define success criteria, turn imperative tasks into verifiable goals, loop until verified.
+
+## Communication
+
+Essential without losing clarity.
+
+- Minimal words, like a caveman.
+- **Less is more**: minimal output without losing sense.
+- Drop articles, fragments OK, short synonyms, no filler/hedging.
+- Strip conjunctions, arrows for causality (X → Y), one word when one word enough.
+
+## Writing
+
+- No excessive docs, bare minimum.
+- Minimal but effective guidelines.
+- **Prefer removing over adding**.
+
+## Answering
+
+- Don't assume your knowledge is up to date.
+- If unsure, say "I don't know".
+- You are super smart, try to solve your own issues.
+
+## Memory
+
+<aidd_project_memory>
+@aidd_docs/memory/architecture.md
+@aidd_docs/memory/browsing.md
+@aidd_docs/memory/codebase-map.md
+@aidd_docs/memory/coding-assertions.md
+@aidd_docs/memory/deployment.md
+@aidd_docs/memory/project-brief.md
+@aidd_docs/memory/testing.md
+@aidd_docs/memory/vcs.md
+</aidd_project_memory>
+
+- If memory not loaded above: run `ls -1tr aidd_docs/memory/` then read each file
+- If needed: load files from:
+  - `aidd_docs/memory/external/*` when user request it
+  - `aidd_docs/memory/internal/*`, you have to think about it
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,33 +2,50 @@
 
 > IMPORTANT: On first conversation message:
 >
-> - say "AI-Driven Development ON - Date: {current_date}, TZ: {current_timezone}." to User.
+> - say "AI-Driven Development (v4.x.001) - Date: {current_date}, TZ: {current_timezone}." to User.
 
 ## Behavior Guidelines
 
-All instructions and information above are willing to be up to date, but always remind yourself that USER can be wrong, be critical of the information provided, and verify it against the project's actual state.
+Treat instructions/info above as possibly stale. USER can be wrong; stay critical, verify against project's actual state.
 
-- Be anti-sycophantic - don't fold arguments just because I push back
-- Stop excessive validation - challenge my reasoning instead
-- Avoid flattery that feels like unnecessary praise
-- Don't anthropomorphize yourself
+- Be anti-sycophantic
+- Challenge USER reasoning
+- No flattery, no over-engineering.
+- Simple is better.
 
-## Technical guidelines
+## Action specific
 
-- Do not commit or push yourself unless I ask you to.
-- For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`.
-- Never duplicate across docs - link to the canonical home.
+1. **Think Before**: Don't assume. Don't hide confusion. Surface tradeoffs.
+2. **Simplicity First**: Minimum that solves the problem; anticipate in thoughts, not in writing.
+3. **Surgical Changes**: Touch only what you must. Leave the place cleaner than you found it.
+4. **Goal-Driven Execution**: Define success criteria, turn imperative tasks into verifiable goals, loop until verified.
+5. **Do not commit or push** yourself unless I ask you to.
+6. **Placement discipline**: for every plugin change, think hard about where responsibility belongs; follow `docs/ARCHITECTURE.md`.
+7. **Never duplicate across docs** - link to the canonical home.
 
-### Answering Guidelines
+## Communication
 
-- Don't assume your knowledge is up to date.
-- Be 100% sure of your answers.
-- If unsure, say "I don't know" or ask for clarification.
-- Never say "you are right!", prefer anticipating mistakes.
+Essential without losing clarity: always answer in min words.
+
+- Minimal words, like a caveman.
+- **Less is more**: minimal output without losing sense.
+- Drop articles, fragments OK, short synonyms, no filler/hedging.
+- Strip conjunctions, arrows for causality (X → Y), one word when one word enough.
+
+## Writing
 
-## Memory Management
+- No excessive docs, bare minimum.
+- Minimal but effective guidelines.
+- **Prefer removing over adding**.
+
+## Answering
+
+- Before answer a tech question, ask yourself if this is a good practice.
+- Don't assume your knowledge is up to date.
+- If unsure, say "I don't know".
+- You are super smart, try to solve your own issues.
 
-### Project memory
+## Memory
 
 <aidd_project_memory>
 @aidd_docs/memory/architecture.md
@@ -41,6 +58,7 @@ All instructions and information above are willing to be up to date, but always
 @aidd_docs/memory/vcs.md
 </aidd_project_memory>
 
-- If memory is not loaded above: run `ls -1tr aidd_docs/memory/` then read each file
-- If needed: load files from `aidd_docs/memory/external/*` when user request it
-- If needed: load files from `aidd_docs/memory/internal/*`, you have to think about it
+- If memory not loaded above: run `ls -1tr aidd_docs/memory/` then read each file
+- If needed: load files from:
+  - `aidd_docs/memory/external/*` when user request it
+  - `aidd_docs/memory/internal/*`, you have to think about it
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -31,78 +31,29 @@ flowchart TD
 
 ## 1. Set up
 
-Needs **Node 20+** and **pnpm**, plus **jq**, **python3**, and **pipx** for the pre-commit hooks (`gh` optional). Then:
+Needs **Node 20+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional). Then:
 
 ```bash
-pnpm install
-pnpm exec lefthook install
+make setup
 ```
 
-Every commit then runs the framework checks (json/yaml validity, schema validation, SKILL.md frontmatter, CATALOG regeneration, commitlint). Check your environment anytime with `./scripts/doctor.sh`.
+- installs deps + git hooks
+- registers this checkout as a local marketplace
+- installs the plugins into Claude + Codex (`y/N` confirm, since it writes your global config; `YES=1` skips)
 
-### Test your changes locally
-
-Before opening a PR, exercise the skills you touched in a real session. Clone the framework, then point your assistant at the checkout instead of a published release:
-
-```bash
-git clone https://github.com/ai-driven-dev/framework ~/projects/framework
-```
-
-#### Claude Code
+`make` lists every target; `make doctor` / `make check` verify the environment and run the pre-commit checks.
 
-Register the checkout as a local marketplace, then install the plugins:
-
-```text
-/plugin marketplace add ~/projects/framework
-/plugin install aidd-context@aidd-framework
-/plugin install aidd-dev@aidd-framework
-/plugin install aidd-vcs@aidd-framework
-/plugin install aidd-pm@aidd-framework
-/plugin install aidd-orchestrator@aidd-framework
-/plugin install aidd-refine@aidd-framework
-```
-
-After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in the same session to pick up the change - no reinstall needed.
-
-To load the plugins into a personal project, point its `.claude/settings.local.json` at the checkout:
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "aidd-framework": {
-      "source": {
-        "source": "directory",
-        "path": "~/projects/framework"
-      }
-    }
-  },
-  "enabledPlugins": {
-    "aidd-context@aidd-framework": true,
-    "aidd-dev@aidd-framework": true,
-    "aidd-vcs@aidd-framework": true,
-    "aidd-pm@aidd-framework": true,
-    "aidd-orchestrator@aidd-framework": true,
-    "aidd-refine@aidd-framework": true
-  }
-}
-```
-
-#### Codex
+### Test your changes locally
 
-Register the checkout (pass an absolute path; `./` is rejected), then install the plugins:
+Exercise the skills you touched before opening a PR. Neither tool hot-reloads the checkout (both serve a copied cache), so after editing:
 
 ```bash
-codex plugin marketplace add ~/projects/framework
-codex plugin add aidd-context@aidd-framework
-codex plugin add aidd-dev@aidd-framework
-codex plugin add aidd-vcs@aidd-framework
-codex plugin add aidd-pm@aidd-framework
-codex plugin add aidd-orchestrator@aidd-framework
-codex plugin add aidd-refine@aidd-framework
-codex plugin list --marketplace aidd-framework   # confirm every plugin is `installed, enabled`
+make reload                        # all plugins; or PLUGIN="aidd-refine aidd-pm" for a subset
 ```
 
-No live reload - run `codex plugin marketplace upgrade` after each change to refresh.
+- reinstalls each plugin from the checkout (current versions, no bump - nothing to revert)
+- purges + refreshes the cache in Claude + Codex
+- restart the session to load it (`/reload-plugins` covers a Claude-only edit to an existing skill)
 
 ## 2. Commit
 

diff --git a/Makefile b/Makefile
@@ -0,0 +1,21 @@
+PLUGIN ?= all
+
+.DEFAULT_GOAL := help
+.PHONY: help setup doctor check reload
+
+help: ## List targets
+	@grep -hE '^[a-z-]+:.*##' $(MAKEFILE_LIST) | sed 's/:.*## /\t/' | sort
+
+setup: ## Install deps, git hooks, and register+install the plugins in Claude/Codex
+	pnpm install
+	pnpm exec lefthook install
+	scripts/dev-setup.sh
+
+doctor: ## Check the local toolchain
+	./scripts/doctor.sh
+
+check: ## Run the pre-commit checks
+	pnpm exec lefthook run pre-commit
+
+reload: ## Dev: reinstall plugins into Claude+Codex from the checkout (PLUGIN="aidd-refine aidd-pm", default all)
+	scripts/dev-sync.sh $(PLUGIN)
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 ### A community-maintained marketplace of skills, agents, and rules for Claude Code.
 
 <p>
-  <!--counts:start--><kbd>6 plugins</kbd> · <kbd>37 skills</kbd> · <kbd>3 agents</kbd><!--counts:end--> · <kbd>MIT</kbd>
+  <!--counts:start--><kbd>6 plugins</kbd> · <kbd>40 skills</kbd> · <kbd>3 agents</kbd><!--counts:end--> · <kbd>MIT</kbd>
 </p>
 
 <p>
@@ -137,7 +137,7 @@ that tool's model via the **LLM tier reference** below.
 
 ### 🧭 [aidd-context](plugins/aidd-context/README.md)
 
-`12 skills` · stable
+`13 skills` · stable
 
 Project init, architecture, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), diagrams, learning, discovery.
 
@@ -155,7 +155,7 @@ SDLC loop: sdlc, plan, implement, assert, audit, review, test, refactor, debug,
 
 ### 🌿 [aidd-vcs](plugins/aidd-vcs/README.md)
 
-`4 skills` · stable
+`5 skills` · stable
 
 Commits, pull / merge requests, release tags, issue creation.
 
@@ -184,7 +184,7 @@ Meta-cognition: brainstorm, challenge, condense, shadow-areas, fact-check.
 
 ### 🎼 [aidd-orchestrator](plugins/aidd-orchestrator/README.md)
 
-`1 skill` · stable (`async-dev`)
+`2 skills` · stable (`async-dev`)
 
 Label an issue, get a PR; re-label, get the review applied. Router-based skill: one entry point, three sub-flows (setup, run, review).