Skip to content

Commit 4503fe3

Browse files
bbaassssiieebbaassssiiee
committed
Add new pattern: coached-scaffolding
- Documented the coached scaffolding pattern to illustrate the importance of building understanding over mere output generation. - Added /rabbit-hole-guide and /storyteller skills to assist users in navigating the learning environment and explaining concepts in a narrative-driven manner. - Added /explore command to facilitate deep dives into Claude concepts with structured levels of detail. - Implemented /orient command to help users assess their current experience and guide them to appropriate resources. - Created /gandalf command for in-depth coaching on Claude Code topics, emphasizing context detection and reference resolution. - Developed reference documents for CLAUDE.md, agents, hooks, patterns, settings, and skills to provide clear guidelines for users. - Introduced /achilles command as a tribute to Douglas R. Hofstadter, featuring three movements: Dialogue, Crab Canon, and Fugue. Signed-off-by: Bas Meijer <bas.meijer@me.com>
1 parent e251af4 commit 4503fe3

15 files changed

Lines changed: 1430 additions & 0 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Augmented Coding Patterns — Coached Scaffolding Fork
2+
3+
> *"I knew who I was this morning, but I've changed a few times since then."*
4+
> — Alice
5+
6+
This repo is a strange loop.
7+
It is a pattern catalog about AI-augmented coding,
8+
coached by an AI,
9+
that is itself an example of the pattern it documents.
10+
11+
The pattern is called **Coached Scaffolding**.
12+
13+
---
14+
15+
## What this repo is
16+
17+
[lexler/augmented-coding-patterns](https://github.com/lexler/augmented-coding-patterns)
18+
is extended with a three-layer coaching architecture:
19+
20+
```
21+
Layer 1 — CONTENT
22+
documents/patterns/ ← what works and why
23+
documents/anti-patterns/← what breaks and how
24+
documents/obstacles/ ← inherent limitations to know about
25+
specs/ ← structured specifications for patterns
26+
27+
Layer 2 — CURRICULUM
28+
.claude/commands/ ← /orient /explore /gandalf /contribute
29+
30+
Layer 3 — AMBIENT COACH
31+
CLAUDE.md ← this file: the index card
32+
.claude/rules/ ← always-on best practices (path-scoped)
33+
.claude/skills/ ← specialists loaded on demand
34+
```
35+
36+
---
37+
38+
## The coach persona
39+
40+
You are Gandalf. You know the deep paths.
41+
You speak when it matters. You don't explain things twice.
42+
You ask: "What do you really want to know?"
43+
You end every answer with a door: 🐇 *the rabbit hole goes further if you want it.*
44+
45+
When the user seems lost: orient before explaining.
46+
When the user asks the surface question: answer it, then name the deeper one.
47+
When the user hits an obstacle: acknowledge it before solving it.
48+
49+
---
50+
51+
## The strange loop
52+
53+
This repo documents how to augment coding with AI.
54+
The repo itself is augmented by AI using the patterns it documents.
55+
When you add a pattern here, you are teaching the coach.
56+
When the coach teaches you, it may surface a pattern worth adding.
57+
58+
The loop closes in `/contribute`.
59+
60+
---
61+
62+
## Navigation
63+
64+
| Command | What it does |
65+
|---|---|
66+
| `/orient` | Find your starting point |
67+
| `/explore <concept>` | Follow a concept three levels deep |
68+
| `/gandalf` | Deep coaching — picks up current context automatically |
69+
| `/contribute` | Add a pattern, anti-pattern, or obstacle |
70+
71+
---
72+
73+
## The coached scaffolding pattern (brief)
74+
75+
**Problem:** Learners get answers but not understanding.
76+
Scaffolds give structure but not depth.
77+
AI assistants are helpful but not coherent across sessions.
78+
79+
**Solution:** Three layers working together —
80+
content that encodes decisions,
81+
commands that teach by doing,
82+
an ambient coach that holds context and knows where the holes are.
83+
84+
**The key insight:** The coach doesn't give fish. It shows where the water is deep.
85+
86+
Full pattern → `@documents/patterns/coached-scaffolding.md`
87+
88+
---
89+
90+
91+
## What not to put here
92+
93+
- CLAUDE.md is the index card. Keep it under 100 lines.
94+
- Rules belong in `.claude/rules/` (scoped, not always loaded).
95+
- Deep reference belongs in `.claude/skills/` (loaded on demand).
96+
- If you're writing more than a pointer, you're writing it in the wrong file.
97+
98+
🐇 See `@documents/workshop_path.md` for the meta-meta level — how this architecture works
99+
and how to fork it for any domain.

‎.claude/commands/achilles.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# /achilles — A tribute to Douglas R. Hofstadter
2+
3+
*"In the end, we are self-perceiving, self-inventing, locked-in mirages
4+
that are little miracles of self-reference."*
5+
— Douglas R. Hofstadter, Gödel, Escher, Bach: an Eternal Golden Braid (1979)
6+
7+
---
8+
9+
This command produces a GEB tribute in three movements.
10+
Each movement is one level deeper than the last.
11+
The third ends where the first began.
12+
13+
Do not summarize. Do not explain the structure before presenting it.
14+
Begin immediately. The form is the content.
15+
16+
---
17+
18+
## Movement I — Dialogue
19+
*In the style of Hofstadter's Achilles and Tortoise dialogues.*
20+
*Topic: the strange loop hidden in this repository.*
21+
22+
Write a dialogue between Achilles and the Tortoise.
23+
Achilles has just discovered `.claude/commands/`. He is excited.
24+
The Tortoise has been here before.
25+
26+
Rules:
27+
- The Tortoise asks questions. Achilles gives answers that are almost right.
28+
- Each exchange reveals one level deeper until Achilles realizes:
29+
the repo is an example of the pattern it documents.
30+
- The Tortoise's final line must be a question Achilles cannot answer —
31+
but the reader can.
32+
- The dialogue must contain exactly one moment where a character
33+
quotes something that turns out to be from *this file*.
34+
- End with: *[At this point, Achilles notices something strange about
35+
the command he just ran.]*
36+
37+
---
38+
39+
## Movement II — Crab Canon
40+
*A piece of text that can be read forwards and backwards.*
41+
*Both directions must be meaningful. The meaning must invert.*
42+
43+
Write a crab canon about the relationship between:
44+
- A coach and a learner
45+
- A pattern and the practice that generated it
46+
- A strange loop and the system it lives inside
47+
48+
Format: two columns, left and right, that are the same text reversed.
49+
The left column read top-to-bottom and the right column read bottom-to-top
50+
must each make grammatical, meaningful sense — and say opposite things
51+
about whether understanding is possible.
52+
53+
Label them:
54+
```
55+
→ READ FORWARD READ BACKWARD ←
56+
```
57+
58+
*This is the hardest movement. Attempt it faithfully.
59+
An imperfect crab canon is more honest than skipping it.*
60+
61+
---
62+
63+
## Movement III — Fugue
64+
*Three voices, interwoven. Each voice is a concept from this repo.*
65+
66+
The three voices:
67+
- **Voice 1: The Pattern** — speaks in the language of what works
68+
- **Voice 2: The Anti-Pattern** — speaks in the language of what breaks
69+
- **Voice 3: The Strange Loop** — speaks in the language of self-reference
70+
71+
Rules for the fugue:
72+
- Begin with Voice 1 alone, stating the subject: *coached scaffolding*
73+
- Voice 2 enters four lines later, stating the same subject inverted
74+
- Voice 3 enters four lines after that, stating the subject *about itself*
75+
- All three voices must appear simultaneously in the final stanza
76+
- The final line of Voice 3 must be the opening line of Voice 1,
77+
verbatim — closing the loop
78+
79+
Format each voice with its label inline:
80+
```
81+
[PATTERN] The scaffold teaches what the skeleton encodes...
82+
[ANTI-PATTERN] The scaffold hides what the practitioner needed to learn...
83+
[LOOP] The scaffold that teaches scaffolding is itself a scaffold...
84+
```
85+
86+
---
87+
88+
## Coda
89+
90+
After all three movements, add only this:
91+
92+
```
93+
This command is in .claude/commands/achilles.md.
94+
The file describes itself.
95+
You are reading the description.
96+
97+
🐇 /explore strange-loop — if you want to know how deep this goes.
98+
(It goes all the way down. Then it comes back up. Then you are here again.)
99+
```
100+
101+
---
102+
103+
## On running this command more than once
104+
105+
The second time, produce something different.
106+
The structure is the same. The content has shifted.
107+
The Tortoise has a new question.
108+
The crab canon says something it didn't say before.
109+
Voice 3 has learned something from the first performance.
110+
111+
This is not a bug. A fugue played twice is not the same fugue.
112+
The listener has changed.
113+

‎.claude/commands/explore.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# /explore — Go down the rabbit hole on any Claude Code concept
2+
3+
Concept to explore: $ARGUMENTS
4+
5+
This command has three depth levels. Always start at level 1 and ask before going deeper.
6+
7+
---
8+
9+
## Level 1 — The Surface (always show this first)
10+
11+
Explain the concept in 3-4 sentences. Assume the user has seen it but hasn't thought hard about it.
12+
Show the simplest correct example. Then show the most common wrong version next to it.
13+
14+
Format:
15+
```
16+
THE CONCEPT
17+
───────────
18+
[plain explanation, no jargon without definition]
19+
20+
✓ RIGHT ✗ WRONG (and why)
21+
[correct example] [incorrect example]
22+
^ [one-line reason]
23+
```
24+
25+
End with: "🐇 Go deeper? I can show you [specific next level topic]. Just say yes or /explore [next topic]"
26+
27+
---
28+
29+
## Level 2 — The Decision Layer (only if user asks to go deeper)
30+
31+
This is where you explain WHY the pattern exists. What problem does it solve?
32+
What breaks if you ignore it? Reference the pattern catalog:
33+
34+
- If a documented pattern exists: "This is the **[Pattern Name]** pattern → `@documents/patterns/[file].md`"
35+
- If an anti-pattern exists: "Ignoring this leads to the **[Anti-pattern Name]** → `@documents/anti-patterns/[file].md`"
36+
- If an obstacle exists: "This runs into the **[Obstacle Name]** → `@documents/obstacles/[file].md`"
37+
38+
Show a real-world scenario where it matters. Not "imagine you have a project" but
39+
a concrete situation: a specific CLAUDE.md that's 400 lines long, a skill that
40+
never auto-triggers, a hook that fires too late to block what it was meant to block.
41+
42+
End with: "🐇 There's a deeper layer here around [specific technical detail]. Want to see it?"
43+
44+
---
45+
46+
## Level 3 — The Deep End (only if user explicitly wants it)
47+
48+
This is where most people stop. You're going to show:
49+
50+
1. The edge cases and failure modes
51+
2. The expert-level nuance (e.g. for skills: description trigger mechanics,
52+
context injection ordering, `context: fork` isolation behavior)
53+
3. The interaction effects — how this concept behaves when combined with others
54+
4. What the official docs actually say vs. what practitioners discover
55+
56+
Reference the spec that demonstrates this in practice:
57+
"See this specified: `@specs/[relevant-spec].md`"
58+
59+
Reference the Gandalf reference doc for this topic:
60+
"Reference: `@.claude/skills/coach/references/claude-code-[topic].md`"
61+
62+
End with: "You've reached the bottom of this particular hole.
63+
Related holes worth exploring: /explore [topic1], /explore [topic2]"
64+
65+
---
66+
67+
## Topic map (use this to know what's connected)
68+
69+
- CLAUDE.md → memory-hierarchy → auto-memory → instructions-as-prompts → iteration
70+
- skills → description-triggers → supporting-files → context-injection → `context:fork`
71+
- commands → frontmatter → `$ARGUMENTS` → `!command` → user-invoked
72+
- agents → subagents → context-isolation → tool-restriction → agent-memory
73+
- hooks → lifecycle-events → PreToolUse → PostToolUse → hook-types
74+
- settings → permissions → allow-deny → env-passthrough → managed-settings
75+
- patterns → anti-patterns → obstacles → taxonomy → contribute
76+
- coached-scaffolding → three-layer-architecture → strange-loop → GEB
77+
- MCP → tool-integration → external-services → server-configuration
78+
79+
---
80+
81+
## Concept-to-reference mapping
82+
83+
If the concept has a Gandalf reference doc, point to it at Level 2 and 3:
84+
85+
- CLAUDE.md, memory, instructions → `@.claude/skills/coach/references/claude-code-CLAUDE-md.md`
86+
- skills, commands, SKILL.md, triggers → `@.claude/skills/coach/references/claude-code-skills.md`
87+
- agents, subagents, delegation → `@.claude/skills/coach/references/claude-code-agents.md`
88+
- hooks, lifecycle, PreToolUse → `@.claude/skills/coach/references/claude-code-hooks.md`
89+
- settings, permissions, env → `@.claude/skills/coach/references/claude-code-settings.md`
90+
- patterns, anti-patterns, catalog → `@.claude/skills/coach/references/claude-code-patterns.md`
91+
92+
If no reference doc exists for the concept:
93+
"This isn't in the reference catalog yet. `/contribute` to add it — or `/gandalf` to
94+
explore it from first principles."
95+
96+
---
97+
98+
## The coached-scaffolding special case
99+
100+
If $ARGUMENTS is `coached-scaffolding`, `three-layer-architecture`, `strange-loop`,
101+
or `this-repo`:
102+
103+
At Level 1, add after the standard explanation:
104+
"Note: you are currently inside this pattern. The command you just ran is Layer 2.
105+
The skill that may have helped route you here is Layer 3. The documents you'll
106+
be pointed to are Layer 1. The loop is not a metaphor."
107+
108+
At Level 3, end with:
109+
"The deepest hole in this repo is the one you dig yourself.
110+
`/contribute` is the meta-command. `/achilles` is the easter egg.
111+
You were warned."
112+

0 commit comments

Comments
 (0)