Add /guide:introspect skill for Introspective Development

.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.16.0",
+                  "version": "2.17.0",
                   "license": "CC-BY-4.0",
                   "keywords": ["onboarding", "guide", "tutorial", "best-practices", "automation", "workflows", "migration"]
           }

.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.16.0",
+  "version": "2.17.0",
   "author": {
     "name": "Ori Nachum"
   },

CLAUDE.md

@@ -6,10 +6,11 @@ This file tells Claude Code (and other AI agents) how to work with this reposito
 
 ## What This Repo Is
 
-A Claude Code guide, packaged as a plugin. There are five skills:
+A Claude Code guide, packaged as a plugin. There are seven skills:
 
 - **`/guide:onboard`** — Interactive getting-started walkthrough for new users
 - **`/guide:ask`** — Q&A skill backed by comprehensive reference documentation in `skills/ask/references/`
+- **`/guide:introspect`** — Introspective Development — audit lifecycle coverage, find gaps, and improve your development environment
 - **`/guide:game-mode`** — Gamified usage tracker that rewards feature breadth and depth with a level system
 - **`/guide:level-up`** — Feature roadmap and personalized next-step coaching
 - **`/guide:migrate-to-claude`** — Smart migration from other AI coding assistants (Cursor, Windsurf, Copilot, Codex, etc.) to Claude Code
@@ -111,6 +112,7 @@ claude-code-guide/
 │   │           │   ├── agent-sdk.md
 │   │           │   ├── hooks-http.md
 │   │           │   ├── ongoing-work.md
+│   │           │   ├── introspective-development.md
 │   │           │   ├── sub-agents.md
 │   │           │   └── team-mode.md
 │   │           ├── daily-workflow.md ...... Story walkthrough
@@ -123,6 +125,8 @@ claude-code-guide/
 │   │           ├── sub-agents-in-monolith.md
 │   │           ├── automated-briefings.md
 │   │           └── migrating-from-other-tools.md
+│   ├── introspect/
+│   │   └── SKILL.md ...................... Introspective Development — audit and improve your project
 │   ├── game-mode/
 │   │   └── SKILL.md ...................... Gamified usage tracker with levels
 │   ├── level-up/

hooks/scripts/migrate-data.sh

@@ -37,7 +37,7 @@ fi
 command -v jq >/dev/null 2>&1 || exit 0
 
 # Define expected feature categories
-EXPECTED='["shell","editing","reading","search","agents","skills","plugins","web","planning","mcp","notebooks","loop","btw","tasks","worktrees"]'
+EXPECTED='["shell","editing","reading","search","agents","skills","plugins","web","planning","mcp","notebooks","loop","btw","tasks","worktrees","introspection"]'
 
 # Add missing fields and categories, preserve all existing data
 # Intentionally does not touch pluginVersion or migrations — those are

hooks/scripts/track-prompt.sh

@@ -40,6 +40,8 @@ if echo "$PROMPT" | grep -qE '^\s*/[a-zA-Z]'; then
       CATEGORY="loop" ;;
     btw)
       CATEGORY="btw" ;;
+    guide:introspect)
+      CATEGORY="introspection" ;;
     guide:*)
       exit 0 ;;  # Our own plugin skills — skip
     help|clear|compact|cost|doctor|init|login|logout|status|model|config|\

hooks/scripts/track-stop.sh

@@ -74,7 +74,7 @@ is_fibonacci "$SESSION" || exit 0
 eval "$(jq -r '
   def multiplier:
     if . == "shell" or . == "editing" or . == "reading" or . == "search" or . == "btw" then 1
-    elif . == "agents" or . == "worktrees" then 100
+    elif . == "agents" or . == "worktrees" or . == "introspection" then 100
     else 10
     end;
 
@@ -116,7 +116,7 @@ dep_met() {
 
 # Level gating: levels 1-2 see intermediate only; 3+ see intermediate + expert
 if [ "$LEVEL" -ge 3 ]; then
-  CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks agents worktrees"
+  CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks agents worktrees introspection"
 else
   CANDIDATES="btw skills plugins web planning notebooks mcp loop tasks"
 fi
@@ -141,7 +141,7 @@ if [ -n "$ELIGIBLE" ]; then
   WEIGHTED=""
   for feat in $ELIGIBLE; do
     case "$feat" in
-      agents|worktrees) WEIGHTED="$WEIGHTED $feat $feat $feat" ;;
+      agents|worktrees|introspection) WEIGHTED="$WEIGHTED $feat $feat $feat" ;;
       *)      WEIGHTED="$WEIGHTED $feat" ;;
     esac
   done
@@ -163,6 +163,7 @@ if [ -n "$ELIGIBLE" ]; then
     agents)    TIP="Sub Agents — delegate complex tasks to run in parallel" ;;
     tasks)     TIP="Task Management — use TaskCreate to break work into tracked steps" ;;
     worktrees) TIP="Worktrees — use isolation: 'worktree' in agents for parallel git work" ;;
+    introspection) TIP="Introspect — run /guide:introspect after a task to find friction and improve your setup" ;;
     *)         TIP="$PICK" ;;
   esac
 
@@ -173,5 +174,5 @@ if [ -n "$ELIGIBLE" ]; then
 
   echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | Try: ${TIP} (/guide:level-up for more)"
 else
-  echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | ${UNIQUE}/15 features (/guide:level-up)"
+  echo "🎮 Lvl ${LEVEL} ${TITLE} | ${SCORE} pts | ${UNIQUE}/16 features (/guide:level-up)"
 fi

skills/ask/references/expert/introspective-development.md

@@ -0,0 +1,132 @@
+---
+title: "Introspective Development"
+parent: "Automation"
+nav_order: 8
+permalink: /introspective-development/
+---
+
+# Introspective Development
+
+> **Level: 🌳 Expert** | **Source:** [Claude Code Guide Plugin](https://github.com/OriNachum/claude-code-guide)
+
+[← Back to Automating Your Workflows](../intermediate/automating-your-workflows.md)
+
+Introspective Development is a paradigm where agents and humans examine their own work, their documentation, and their development environment — then act on what they find. The agent asks itself: **"How could I have done it better?"** and encodes the answer as durable improvements.
+
+Documentation is code. NotebookLM is the compiler. Skills are the executable output.
+
+## The Four Dimensions
+
+### 1. Documentation Loop
+
+Work produces documentation — CLAUDE.md updates, skill descriptions, changelogs. That documentation becomes context for the next session. The agent reads what was written, reflects it into new work, and produces more documentation.
+
+```text
+spec → plan → code → changelog → context for the next spec
+```
+
+This is **Natural Language Memory (NLM)** — agents use generated docs as durable memory across sessions. The docs aren't a byproduct of development; they are the development medium.
+
+### 2. Self-Reflection
+
+Examining what worked and what didn't:
+
+- Did the session reveal misunderstandings or repeated corrections?
+- Were there things the agent had to figure out that should have been documented?
+- Did the user correct the agent's approach? That correction should become durable guidance.
+
+Self-reflection feeds the improvement loop — observations become skills, hooks, or CLAUDE.md entries.
+
+### 3. Active Documentation Review
+
+After producing documentation, deliberately review it through different lenses:
+
+- **Audio review** — feed docs into NotebookLM to generate podcast-style overviews, catch gaps and unclear explanations that aren't obvious when reading
+- **AI conversations** — discuss docs with agents: "explain this back to me," "what's missing," "what would confuse a newcomer"
+- **User-story demos** — write scenarios that walk through actual usage, revealing design gaps
+- **Fix-forward cycle** — issues found flow back as tasks: bug fixes, doc rewrites, design improvements
+
+This is the "documentation as code, NotebookLM as compiler" principle. If the compiled output (podcast, overview, summary) sounds wrong, the source docs need fixing.
+
+### 4. Environment Self-Improvement
+
+Working with agents reveals friction — tasks that take more effort than they should, patterns that repeat without automation, context that gets lost between sessions. Act on these observations:
+
+- **Skills** — encode repeated workflows as slash commands
+- **Hooks** — automate event-driven actions (post-tool, pre-commit, session-end)
+- **MCP servers or agent skills** — wire external integrations for tools the agent needs
+- **Sub-agents** — create specialists for tasks that benefit from dedicated context
+- **CLAUDE.md updates** — capture hard-won project knowledge so future sessions start better
+- **Scripts** — reduce cognitive complexity of common tasks
+
+The loop: **work → notice friction → improve the environment → work better → notice new friction**.
+
+## The Development Lifecycle
+
+Introspective Development verifies that a project supports every 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 |
+| **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 |
+| **Clear** | Agent knows how to clean up — compact history, archive, close |
+
+Gaps in any phase create friction. Introspection finds those gaps and proposes fixes.
+
+## Using the Introspect Skill
+
+```text
+/guide:introspect                    # Infers focus from context
+/guide:introspect agent skills       # Focus on a specific area
+/guide:introspect auto               # Enable auto-introspection after PRs
+/guide:introspect remind             # Get reminders after PRs instead
+/guide:introspect off                # Manual only
+```
+
+**Focus inference:**
+
+- After recent work (plan completed, PR merged): focuses on that work
+- On a clean project: asks "Cover the whole project?" for a full review
+- With text: uses your text as the focus area
+
+**The process:**
+
+1. **Scan** — read project state (CLAUDE.md, skills, hooks, plugins, sub-agents, MCP/agent skills, scripts, tests, CI, linting, docs, git history)
+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)
+
+## Trigger Levels
+
+Control whether introspection runs automatically:
+
+| Level | Behavior |
+|---|---|
+| **off** (default) | You manually run `/guide:introspect` |
+| **remind** | Agent reminds you after PR merge: "Want to introspect?" |
+| **auto** | Agent runs introspection itself after PR merge |
+
+Toggle with `/guide:introspect auto|remind|off` or natural language ("call it automatically", "stop running it by yourself").
+
+The setting persists across plugin updates. After changing the trigger level, restart Claude Code for it to take effect.
+
+## Origin
+
+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
+- **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.
+
+## See Also
+
+- [Hooks](../intermediate/hooks.md) — event-driven automation that introspection may suggest adding
+- [Skills](../intermediate/skills.md) — the building blocks introspection creates
+- [Sub Agents](sub-agents.md) — specialists introspection may recommend
+- [Best Practices](../intermediate/best-practices.md) — patterns that reduce the friction introspection finds

skills/game-mode/SKILL.md

@@ -84,7 +84,8 @@ Present the available commands:
     "loop":      { "count": 0, "lastUsed": null },
     "btw":       { "count": 0, "lastUsed": null },
     "tasks":     { "count": 0, "lastUsed": null },
-    "worktrees": { "count": 0, "lastUsed": null }
+    "worktrees": { "count": 0, "lastUsed": null },
+    "introspection": { "count": 0, "lastUsed": null }
   },
   "tokens": {
     "read": 0,
@@ -98,7 +99,7 @@ Present the available commands:
 ```
 
 1. Tell the user game mode is now active. Mention:
-   - Tool usage is being tracked across 15 feature categories
+   - Tool usage is being tracked across 16 feature categories
    - Use `/guide:game-mode stats` to see their dashboard
    - Use `/guide:game-mode off` to pause tracking
    - Data is stored locally and never transmitted
@@ -125,7 +126,7 @@ Present the available commands:
 |---|---|---|
 | Beginner | x1 | shell, editing, reading, search, btw |
 | Intermediate | x10 | skills, plugins, web, planning, notebooks, mcp, loop, tasks |
-| Expert | x100 | agents, worktrees |
+| Expert | x100 | agents, worktrees, introspection |
 
 1. Compute: `raw_points = sum(feature.count * multiplier)` and `score = sqrt(raw_points)` to 2 decimal places
 1. Count unique features (count > 0)
@@ -163,9 +164,10 @@ Present the available commands:
 |  ⚪ Loop/Schedule    I       0       0   never        |
 |  ⚪ Task Mgmt        I       0       0   never        |
 |  ⚪ Worktrees        E       0       0   never        |
+|  ⚪ Introspection    E       0       0   never        |
 +=======================================================+
 |  Raw: 1053 pts | Score: sqrt(1053) = 32.45            |
-|  Features: 10/15 unlocked                             |
+|  Features: 10/16 unlocked                             |
 |  Tokens: ~12.4K read, ~3.1K write                     |
 |  Next level: Master (score 55+, 10+ features)         |
 |  Migrated: unknown → 2.2.0 (2026-03-09)              |