From 56cb78f7bf315836ee4eadd67c17f83b79b4b0fe Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Sun, 12 Apr 2026 01:26:27 +0300 Subject: [PATCH 1/2] Apply introspection findings: update docs, add linting config, refine skill Fixes from running /guide:introspect on this repo after PR #49: - Remove AGENT.md references from skill (Agentic Folders deferred) - Add introspect skill to README.md and index.md - Add markdownlint config to repo root for contributor consistency - Add "Clear" phase guidance to CLAUDE.md Git Workflow section - Fix ordered list numbering in SKILL.md Co-Authored-By: Claude Opus 4.6 (1M context) --- .markdownlint-cli2.yaml | 12 ++++++++++++ CLAUDE.md | 9 +++++++++ README.md | 3 ++- index.md | 4 +++- .../expert/introspective-development.md | 4 ++-- skills/introspect/SKILL.md | 15 +++++---------- 6 files changed, 33 insertions(+), 14 deletions(-) create mode 100644 .markdownlint-cli2.yaml diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..e6b02b5 --- /dev/null +++ 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 index 511ba97..05b6e71 100644 --- 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 index f9be4e9..9dbf34a 100644 --- 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. diff --git a/index.md b/index.md index e425895..ed50400 100644 --- 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 Plugin in action diff --git a/skills/ask/references/expert/introspective-development.md b/skills/ask/references/expert/introspective-development.md index cf2196a..7346d3e 100644 --- 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 diff --git a/skills/introspect/SKILL.md b/skills/introspect/SKILL.md index 06101df..abda2d9 100644 --- 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 From 0e8080dee487737cd38a7af17e4af34fd4ea164d Mon Sep 17 00:00:00 2001 From: Ori Nachum Date: Sun, 12 Apr 2026 01:35:43 +0300 Subject: [PATCH 2/2] Fix review comments: version bump, Contributing count, Agentic Folders ref MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Bump version 2.17.0 → 2.17.1 (patch: content changes to shipped skill) - Fix Contributing section: "five skills" → "seven skills", add introspect/ - Soften Agentic Folders reference in Origin section (future consideration) Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- README.md | 2 +- skills/ask/references/expert/introspective-development.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1e2a4bd..6dc4b13 100644 --- 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 index df6923a..8e0611d 100644 --- 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/README.md b/README.md index 9dbf34a..7a37a5c 100644 --- a/README.md +++ b/README.md @@ -253,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/skills/ask/references/expert/introspective-development.md b/skills/ask/references/expert/introspective-development.md index 7346d3e..e1eb516 100644 --- a/skills/ask/references/expert/introspective-development.md +++ b/skills/ask/references/expert/introspective-development.md @@ -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.