OriNachum · OriNachum · Apr 11, 2026 · Apr 11, 2026 · Apr 11, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
                   "name": "guide",
                   "source": "./",
                   "description": "Claude Code guide — interactive onboarding walkthrough and Q&A on setup, best practices, automation, and effective workflows",
-                  "version": "2.17.0",
+                  "version": "2.17.1",
                   "license": "CC-BY-4.0",
                   "keywords": ["onboarding", "guide", "tutorial", "best-practices", "automation", "workflows", "migration"]
           }

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "guide",
   "description": "A Claude Code guide — skills for interactive onboarding and Q&A on setup, best practices, automation, and effective workflows",
-  "version": "2.17.0",
+  "version": "2.17.1",
   "author": {
     "name": "Ori Nachum"
   },

diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -0,0 +1,12 @@
+# Project markdownlint-cli2 configuration
+config:
+  default: true
+  # MD013: Line length — disabled (content-heavy docs with tables)
+  MD013: false
+  # MD060: Table pipe spacing — disabled (stylistic preference)
+  MD060: false
+
+# Ignore patterns
+ignores:
+  - "node_modules/**"
+  - ".local/**"
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -223,6 +223,15 @@ Installed plugins are cached at `~/.claude/plugins/cache`. **Version is the cach
 
 Before staging or committing changes, check the current branch. If you are on `main`, create a new descriptive branch first — never commit directly to `main`.
 
+### After completing work
+
+When a task is done and merged, clean up:
+
+- Compact or clear conversation history if context is getting long
+- Delete merged feature branches locally: `git branch -d feature/branch-name`
+- Close related GitHub issues (use `closes #N` in commit messages for auto-close)
+- Run `/guide:introspect` to review what could be improved for next time
+
 ---
 
 ## How to Edit

diff --git a/README.md b/README.md
@@ -87,10 +87,11 @@ claude plugin install guide@claude-code-guide
 
 ### Usage
 
-Once installed, five skills are available:
+Once installed, seven skills are available:
 
 - **`/guide:onboard`** — Interactive getting-started walkthrough. Guides you through environment setup, your first session, and best practices.
 - **`/guide:ask`** — Ask any question about Claude Code features. Reads relevant reference docs to give accurate, detailed answers.
+- **`/guide:introspect`** — Introspective Development. Audit your project's lifecycle coverage, find gaps in tooling and docs, and auto-fix what it finds. Run after a task to ask "How could I have done it better?"
 - **`/guide:game-mode`** — Enable Game Mode. The guide locally tracks your usage of Claude, assigns a level per feature area, and helps you master Claude Code.
 - **`/guide:level-up`** — Feature roadmap and personalized next-step coaching. Shows what to learn next based on your current skill level.
 - **`/guide:migrate-to-claude`** — Migrate your Cursor, Windsurf, Copilot, Continue, Aider, Cody, or Codex configs to Claude Code. Discovers configs, trims bloat, and proposes a clean migration plan.
@@ -252,7 +253,7 @@ claude-code-guide/
 
 ## Contributing
 
-Contributions welcome! The five skills live at `skills/onboard/`, `skills/ask/`, `skills/game-mode/`, `skills/level-up/`, `skills/migrate-to-claude/`, and `skills/visualize-setup/`. Reference docs are in `skills/ask/references/` and hooks are in `hooks/`.
+Contributions welcome! The seven skills live at `skills/onboard/`, `skills/ask/`, `skills/introspect/`, `skills/game-mode/`, `skills/level-up/`, `skills/migrate-to-claude/`, and `skills/visualize-setup/`. Reference docs are in `skills/ask/references/` and hooks are in `hooks/`.
 
 ## License
 

diff --git a/index.md b/index.md
@@ -40,13 +40,15 @@ A community guide to **Claude Code** — setup, best practices, automation, and
 
 This is a community-maintained resource. It is **not** an official Anthropic product.
 
-The guide is packaged as a Claude Code plugin with five skills:
+The guide is packaged as a Claude Code plugin with seven skills:
 
 - **`/guide:onboard`** — Interactive getting-started walkthrough
 - **`/guide:ask`** — Ask any question about Claude Code features
+- **`/guide:introspect`** — Audit lifecycle coverage, find gaps, and improve your development environment
 - **`/guide:game-mode`** — Gamified usage tracker with levels
 - **`/guide:level-up`** — Feature roadmap and personalized coaching
 - **`/guide:migrate-to-claude`** — Migrate configs from other AI coding assistants
+- **`/guide:visualize-setup`** — Interactive dashboard of skills, MCP servers, and setup
 
 <img width="600" alt="Plugin in action" src="https://github.com/user-attachments/assets/3643154f-00e9-4793-886e-e49adfee54ef" />
 

diff --git a/skills/ask/references/expert/introspective-development.md b/skills/ask/references/expert/introspective-development.md
@@ -68,7 +68,7 @@ Introspective Development verifies that a project supports every phase of the de
 | Phase | What "supported" means |
 |---|---|
 | **Plan** | Architecture docs exist, planning guidance in CLAUDE.md or a skill |
-| **Implement** | Code is navigable — AGENT.md in key folders, conventions documented, scripts reduce complexity |
+| **Implement** | Code is navigable — conventions documented, scripts reduce complexity |
 | **Test** | Test suite exists, CI runs it, agent knows how to invoke tests |
 | **PR** | PR workflow documented or scripted — format, checks, reviewers |
 | **Iterate** | Review feedback loop works — agent can read comments, fix, push |
@@ -98,7 +98,7 @@ Gaps in any phase create friction. Introspection finds those gaps and proposes f
 2. **Analyze** — evaluate through the four dimensions
 3. **Lifecycle check** — verify each phase is supported
 4. **Report** — present findings in plan mode for your review
-5. **Fix** — apply approved changes (create/update CLAUDE.md, AGENT.md, skill stubs, linting configs)
+5. **Fix** — apply approved changes (create/update CLAUDE.md, skill stubs, linting configs)
 
 ## Trigger Levels
 
@@ -119,7 +119,7 @@ The setting persists across plugin updates. After changing the trigger level, re
 Introspective Development originated in the [Culture](https://github.com/OriNachum/culture) project as "Reflective Development" — a paradigm where agents develop by reflecting on real work, not by configuration. The concept evolved through several blog posts:
 
 - **Workbench Development** — scoping agents to specific folders for reliable, isolated work
-- **Agentic Folders** — placing AGENT.md in key directories so agents understand context per-folder
+- **Agentic Folders** — placing instruction files in key directories so agents understand context per-folder (future consideration)
 - **Code as Documentation** — skills as live, executable documentation that can't silently rot
 
 The `/guide:introspect` skill packages these ideas into a practical tool any project can use.

diff --git a/skills/introspect/SKILL.md b/skills/introspect/SKILL.md
@@ -54,20 +54,17 @@ If the intent is unclear, ask the user which level they want.
 2. Read `${CLAUDE_PLUGIN_ROOT}/.local/game-data.json` — if the file doesn't exist, start with `{}`
 3. Set `.introspectConfig.triggerLevel` to the chosen level (`auto`, `remind`, or `off`)
 4. Write the updated game-data.json
-
-4. If level is `auto`:
+5. If level is `auto`:
    - Edit this file's frontmatter: set `disable-model-invocation: false`
    - Search the project for a PR review skill: look in `.claude/skills/`, `skills/`, and installed plugins for any skill whose description mentions "PR", "pull request", or "review"
    - If found: ask the user "Found **[skill name]**. Update it to call `/guide:introspect` after PR merge?"
    - If not found: ask the user "No PR review skill found. Create one?" AND add to CLAUDE.md: "After merging a PR, run `/guide:introspect` to review what could be improved."
    - Tell the user: "Restart Claude Code for automatic introspection to take effect."
-
-5. If level is `remind`:
+6. If level is `remind`:
    - Keep this file's frontmatter as `disable-model-invocation: true`
    - Same PR skill search as `auto`, but the instruction becomes: "After merging a PR, remind the user: 'Want to introspect? Run `/guide:introspect`'"
    - Tell the user: "Restart Claude Code for the reminder to take effect."
-
-6. If level is `off`:
+7. If level is `off`:
    - Edit this file's frontmatter: set `disable-model-invocation: true`
    - Tell the user: "Automatic introspection disabled. You can still run `/guide:introspect` manually anytime. Restart Claude Code for the change to take effect."
 
@@ -102,7 +99,7 @@ Gather project state relevant to the focus. Read what exists, note what's missin
 
 | Area | What to look for |
 |---|---|
-| **Instruction files** | CLAUDE.md, AGENT.md files — do they exist? Are they current? |
+| **Instruction files** | CLAUDE.md — does it exist? Is it current? |
 | **Skills** | `skills/`, `.claude/skills/` — what workflows are encoded? |
 | **Hooks** | `hooks/`, `.claude/hooks/` — what events are automated? |
 | **Plugins** | `.claude-plugin/`, installed plugins — what extensions exist? |
@@ -124,7 +121,6 @@ Evaluate findings through the four dimensions of Introspective Development:
 
 - Is CLAUDE.md current and accurate?
 - Do skills have descriptions that match what they actually do?
-- Are AGENT.md files present in key directories?
 - Would an agent landing here for the first time know how to navigate?
 
 #### Dimension 2: Self-Reflection
@@ -152,7 +148,7 @@ Evaluate whether the project supports each phase of the development lifecycle:
 | Phase | What "supported" means |
 |---|---|
 | **Plan** | Architecture docs exist, planning guidance in CLAUDE.md or a skill |
-| **Implement** | Code is navigable — AGENT.md in key folders, conventions documented, scripts reduce complexity |
+| **Implement** | Code is navigable — conventions documented, scripts reduce complexity |
 | **Test** | Test suite exists, CI runs it, agent knows how to invoke (documented or scripted) |
 | **PR** | PR workflow is documented or scripted — what to include, format, checks |
 | **Iterate** | Review feedback loop works — agent can read comments, fix, push |
@@ -210,7 +206,6 @@ Apply only the approved fixes. For each fix:
 **What you CAN do:**
 
 - Create or update CLAUDE.md sections
-- Create AGENT.md files in key directories
 - Create skill stubs (basic SKILL.md with description — user fills in details)
 - Add or update linting configs
 - Update existing skill descriptions