specdacular 0.10.1 → 0.11.0

package/specdacular/workflows/generate-learn-skill.md

@@ -0,0 +1,214 @@
+<purpose>
+Generate a project-specific /{namespace}:learn skill that captures coding lessons into the project's docs/ files. Reads existing docs to customize the skill's target table, section headings, and formatting.
+
+**Output:** `.claude/commands/{namespace}/learn.md`
+</purpose>
+
+<philosophy>
+
+## Read, Don't Guess
+
+The skill must reference actual doc files with accurate descriptions. Read every doc before generating the skill.
+
+## Match The Format
+
+Each project's docs have their own style. The learn skill should write entries that match — scan existing entries for format patterns (bullet style, heading levels, code block conventions).
+
+</philosophy>
+
+<process>
+
+<step name="check_prerequisites">
+Verify that docs exist.
+
+```bash
+ls docs/*.md 2>/dev/null
+```
+
+**If no docs found:**
+```
+No docs/ folder found. The learn skill needs docs to write to.
+
+Run /specd.docs first to generate topic-based documentation.
+```
+End workflow.
+
+Continue to derive_namespace.
+</step>
+
+<step name="derive_namespace">
+Determine the skill namespace.
+
+**If user provided `$ARGUMENTS`:** Use first non-flag token as namespace.
+
+**If no argument:** Infer from project:
+```bash
+basename $(pwd) | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g'
+```
+
+Use AskUserQuestion:
+- header: "Namespace"
+- question: "What namespace for your skill? (invoked as `/{ns}:learn`)"
+- options:
+  - "{inferred name} (Recommended)" — Use the detected project name
+  - "Custom" — Enter a different namespace
+
+Set `$NAMESPACE`.
+
+Continue to analyze_docs.
+</step>
+
+<step name="analyze_docs">
+Read all doc files and build the target mapping.
+
+**For each file in docs/:**
+
+1. Read the file
+2. Extract:
+   - Filename (e.g., `css-and-styles.md`)
+   - Top-level `##` section headings
+   - Brief description of what it covers (from first paragraph or heading pattern)
+   - Entry format — how existing entries are written (bullet style, one-liners vs paragraphs)
+
+3. Check if `docs/rules.md` exists — if yes, extract its section headings too (these become the rule categories)
+
+**Build `$DOC_TABLE`** — a markdown table with one row per doc:
+```
+| Doc | Content |
+|-----|---------|
+| `docs/rules.md` | Project-wide rules (Styling, Components, ...) |
+| `docs/css-and-styles.md` | Fonts, colors, spacing, SCSS |
+| `docs/react-query-and-apis.md` | Hooks, mutations, API calls |
+| ... | ... |
+```
+
+**Build `$RULES_SECTIONS`** — list of section headings in rules.md (if it exists).
+
+Continue to generate_skill.
+</step>
+
+<step name="generate_skill">
+Generate the learn skill file.
+
+```bash
+mkdir -p .claude/commands/$NAMESPACE
+```
+
+Write `.claude/commands/$NAMESPACE/learn.md` with the following content (replacing all template variables):
+
+```markdown
+# /{NAMESPACE}:learn — Capture a lesson into project docs
+
+Capture a coding lesson, mistake, or pattern from the current conversation and add it to the appropriate documentation files so future sessions don't repeat the same mistake.
+
+## Input
+
+The user may provide an explicit lesson as an argument: `$ARGUMENTS`
+
+If no argument is provided, infer the lesson from the recent conversation — look for corrections, mistakes, or new patterns that were discussed.
+
+## Steps
+
+### 1. Identify the lessons
+
+Extract one or more lessons from the conversation or argument. Each lesson should be a clear, actionable statement. Examples:
+- "Never use X — use Y instead"
+- "Always wrap Z in an error boundary"
+- "Use the existing useX hook instead of writing custom fetch logic"
+
+### 2. Classify each lesson
+
+For each lesson, determine:
+
+**Type:**
+- **Rule** — A hard constraint ("never X", "always Y"). Goes into `docs/rules.md` AND a topic doc.
+- **Pattern** — A technique or code example ("here's how to do X"). Goes into a topic doc only.
+
+**Target doc — pick from:**
+
+{$DOC_TABLE}
+
+**Section — read the target doc to find the right section heading to append under.**
+
+### 3. Present to the user for confirmation
+
+Show each lesson with your suggested classification. Use AskUserQuestion to let the user confirm or adjust the destination for each lesson.
+
+For each lesson, present:
+- The lesson text (editable — the user can tweak the wording)
+- Whether it's a Rule (→ rules.md + topic doc) or Pattern (→ topic doc only)
+- Which topic doc it goes to
+
+### 4. Check for duplicates
+
+Before writing, read the target files and scan for similar existing rules or patterns. If something similar exists, ask the user: "This looks similar to an existing entry: '...'. Update it, add as new, or skip?"
+
+### 5. Write the lessons
+
+**For rules (→ rules.md):**
+- Read `docs/rules.md`
+- Find the right section heading
+- Append the rule as a bullet point matching existing format
+- Use the pattern: `- Never/Always [action] — [what to use instead]`
+
+**For topic docs:**
+- Read the target doc
+- Find the most relevant section heading
+- Append the lesson under that section
+- If it's a pattern with a code example, include the code block
+- If no existing section fits, append a new section at the end
+
+### 6. Confirm what was written
+
+After writing, summarize what was added and where.
+
+## Important
+
+- Do NOT commit automatically — let the user batch commits
+- Keep rule entries short (one line) — details go in the topic doc
+- Match the existing writing style and formatting of each doc
+- If the user says `/{NAMESPACE}:learn` with no context and no argument, ask: "What's the lesson?"
+```
+
+**Replace in the template:**
+- All `{NAMESPACE}` → `$NAMESPACE`
+- `{$DOC_TABLE}` → the actual doc table built in analyze_docs
+- If `docs/rules.md` doesn't exist, remove the rules.md references and simplify — all lessons go to topic docs only
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Present what was generated.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL GENERATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Created: .claude/commands/{namespace}/learn.md
+
+Usage:
+  /{namespace}:learn                    — Infer lesson from conversation
+  /{namespace}:learn "never use X"      — Explicit lesson
+
+Targets these docs:
+{list of doc files}
+
+To refine with evals and benchmarks:
+  /skill-creator — Anthropic plugin for skill testing and improvement
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- docs/ read and analyzed for structure
+- Namespace derived from project or user input
+- .claude/commands/{namespace}/learn.md created
+- Doc target table matches real docs with accurate descriptions
+- Skill format matches existing doc entry styles
+- No auto-commit
+</success_criteria>

package/specdacular/workflows/new.md

@@ -90,21 +90,22 @@ End main workflow.
 
 **Check for codebase docs:**
 ```bash
-ls .specd/codebase/*.md 2>/dev/null
+[ -f "CLAUDE.md" ] && cat CLAUDE.md || echo "no_claude_md"
+ls docs/*.md 2>/dev/null
 ```
 
-**If codebase docs found:**
+**If CLAUDE.md or docs/ found:**
 ```
 Found codebase documentation. I'll reference these when defining requirements.
 ```
-Read the available docs to understand project structure, code patterns, and architecture.
+Read the CLAUDE.md routing table and referenced docs to understand project structure, code patterns, and architecture.
 
 **If no codebase docs found:**
 Use AskUserQuestion:
 - header: "No Codebase Docs"
 - question: "I didn't find codebase documentation. How should we proceed?"
 - options:
-  - "Run map-codebase first" — Creates AI-optimized docs
+  - "Run /specd.docs first" — Generates topic docs and CLAUDE.md routing table
   - "Continue without" — Proceed without codebase context
   - "Custom location" — Docs are elsewhere
 

package/specdacular/workflows/orchestrator/new.md

@@ -13,10 +13,10 @@ Called from the main `new.md` workflow after orchestrator mode detection.
 <step name="load_system_docs">
 Read system-level codebase docs:
 
-- `.specd/codebase/PROJECTS.md` — Project registry
-- `.specd/codebase/TOPOLOGY.md` — Communication patterns
-- `.specd/codebase/CONTRACTS.md` — Shared interfaces
-- `.specd/codebase/CONCERNS.md` — System-level concerns
+- `docs/PROJECTS.md` — Project registry
+- `docs/TOPOLOGY.md` — Communication patterns
+- `docs/CONTRACTS.md` — Shared interfaces
+- `docs/CONCERNS.md` — System-level concerns
 
 Read project list from `.specd/config.json` `"projects"` array.
 

package/specdacular/workflows/orchestrator/plan.md

@@ -13,16 +13,16 @@ Called from the main `plan.md` workflow after orchestrator mode detection.
 <step name="load_cross_project_context">
 Load system-level and sub-project context.
 
-**System-level codebase docs:**
-- `.specd/codebase/PROJECTS.md` — Project registry
-- `.specd/codebase/TOPOLOGY.md` — Communication patterns
-- `.specd/codebase/CONTRACTS.md` — Shared interfaces
+**System-level docs:**
+- `docs/PROJECTS.md` — Project registry
+- `docs/TOPOLOGY.md` — Communication patterns
+- `docs/CONTRACTS.md` — Shared interfaces
 
 **Sub-project context:**
 From task config.json `"projects"` array, for each project:
 - Read `{project-path}/.specd/tasks/{task-name}/FEATURE.md` — Project-specific requirements
-- Read `{project-path}/.specd/codebase/MAP.md` — Project code overview (if exists)
-- Read `{project-path}/.specd/codebase/PATTERNS.md` — Project patterns (if exists)
+- Read `{project-path}/CLAUDE.md` — Project routing table and docs (if exists)
+- Read `{project-path}/docs/*.md` — Project topic docs (if exists)
 
 ```
 Orchestrator mode: {N} projects involved in this task.

package/commands/specd.codebase.map.md

@@ -1,72 +0,0 @@
----
-name: specd.codebase.map
-description: Analyze codebase with parallel agents to produce AI-optimized documentation
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
----
-
-<objective>
-Analyze existing codebase using parallel mapper agents to produce 4 AI-optimized documents.
-
-Each mapper agent explores a focus area and **writes documents directly** to `.specd/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
-
-Output: .specd/codebase/ folder with 4 documents designed for Claude consumption.
-</objective>
-
-<execution_context>
-@~/.claude/specdacular/workflows/map-codebase.md
-</execution_context>
-
-<context>
-**These documents are FOR CLAUDE, not humans.**
-
-Each document answers a question Claude can't get from reading code:
-
-| Document | Question it answers |
-|----------|---------------------|
-| MAP.md | "Where is X? What functions exist?" |
-| PATTERNS.md | "How do I write code that fits here?" |
-| STRUCTURE.md | "Where do I put new code?" |
-| CONCERNS.md | "What will bite me?" |
-
-**Principle:** Don't document what Claude can grep. Document tribal knowledge, gotchas, and patterns.
-</context>
-
-<when_to_use>
-**Use map-codebase for:**
-- First time working with a codebase
-- Before planning a new feature
-- After significant refactoring
-- Onboarding Claude to an unfamiliar repo
-
-**Skip map-codebase for:**
-- Trivial codebases (<10 files)
-- When you already have recent codebase docs
-</when_to_use>
-
-<process>
-1. Check if .specd/codebase/ already exists (offer to refresh or skip)
-2. Create .specd/codebase/ directory
-3. Spawn 4 parallel specd-codebase-mapper agents:
-   - Agent 1: map focus → writes MAP.md
-   - Agent 2: patterns focus → writes PATTERNS.md
-   - Agent 3: structure focus → writes STRUCTURE.md
-   - Agent 4: concerns focus → writes CONCERNS.md
-4. Wait for agents to complete, collect confirmations
-5. Verify all 4 documents exist
-6. Commit codebase map
-7. Report completion
-</process>
-
-<success_criteria>
-- [ ] .specd/codebase/ directory created
-- [ ] All 4 documents written by mapper agents
-- [ ] Documents contain real code examples (not placeholders)
-- [ ] Parallel agents completed without errors
-</success_criteria>

package/commands/specd.codebase.review.md

@@ -1,39 +0,0 @@
----
-name: specd.codebase.review
-description: "Review and edit codebase context files section by section"
-argument-hint: ""
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - AskUserQuestion
----
-
-<objective>
-Walk through and review a codebase context file (.specd/codebase/*.md) section by section. Confirm, edit, remove, or re-map individual sections.
-
-Output: Updated context file with reviewed/edited sections and updated timestamps.
-</objective>
-
-<execution_context>
-Follow the context-manual-review workflow:
-@~/.claude/specdacular/workflows/context-manual-review.md
-</execution_context>
-
-<context>
-**Context workflows:**
-@~/.claude/specdacular/workflows/context-manual-review.md
-@~/.claude/specdacular/workflows/context-add.md
-</context>
-
-<success_criteria>
-- [ ] User selects a context file to review
-- [ ] Section list shown with tag status
-- [ ] User can confirm, edit, remove, or re-map each section
-- [ ] Timestamps updated after review
-- [ ] Changes committed
-</success_criteria>