@slamb2k/mad-skills 2.0.6 → 2.0.8

package/skills/brace/SKILL.md

@@ -1,30 +1,25 @@
 ---
 name: brace
-description: >
-  Initialize any project directory with the GOTCHA/BRACE framework for agentic
-  AI systems. Creates the 6-layer structure (Goals, Orchestration, Tools,
-  Context, Hard prompts, Args), BRACE build methodology, and a project
-  CLAUDE.md. Recommends claude-mem for persistent memory. Idempotent — safe
-  to run on existing projects. Triggers: "init gotcha", "setup brace", "brace",
-  "initialize framework", "bootstrap gotcha".
-argument-hint: [--no-brace] [--force]
+description: 'Initialize any project directory with the GOTCHA/BRACE framework for agentic AI systems. Creates the 6-layer structure (Goals, Orchestration, Tools, Context, Hard prompts, Args), BRACE build methodology, and a project CLAUDE.md. Recommends claude-mem for persistent memory. Idempotent — safe to run on existing projects. Triggers: "init gotcha", "setup brace", "brace", "initialize framework", "bootstrap gotcha".'
+argument-hint: "[--no-brace] [--force]"
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
 # Brace - GOTCHA/BRACE Framework Bootstrap
 
 When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
-Pick ONE tagline at random — vary your choice each time:
+Pick ONE tagline at random — vary your choice each time.
+CRITICAL: Reproduce the banner EXACTLY character-for-character. The first line of the art has 4 leading spaces — you MUST preserve them.
 
 ```
 {tagline}
 
-    ██╗██████╗ ██████╗  █████╗  ██████╗███████╗
+⠀   ██╗██████╗ ██████╗  █████╗  ██████╗███████╗
    ██╔╝██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔════╝
   ██╔╝ ██████╔╝██████╔╝███████║██║     █████╗
  ██╔╝  ██╔══██╗██╔══██╗██╔══██║██║     ██╔══╝
 ██╔╝   ██████╔╝██║  ██║██║  ██║╚██████╗███████╗
 ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝
-
 ```
 
 Taglines:
@@ -37,15 +32,246 @@ Taglines:
 - Structural integrity confirmed!
 - Brace for impact!
 
-Follow instructions in: [instructions.md](instructions.md)
+---
+
+Initialize any project directory with the GOTCHA/BRACE framework. Idempotent —
+safe to re-run on existing projects. Content templates and subagent prompts
+are in `references/`.
 
-## Subagent Architecture
+**Key principle:** Scan first, present plan, get approval, then act.
 
-- Phase 1 (scan): **Bash** subagent, **haiku** model
-- Phase 4 (scaffold): **general-purpose** subagent (content generation)
-- Phase 5 (verify): **Bash** subagent, **haiku** model
+Phase prompts: `references/phase-prompts.md`
+Scaffold manifest: `references/scaffold-manifest.md`
+Report format: `references/report-template.md`
+
+---
 
 ## Flags
 
-- `--no-brace` — Skip BRACE build methodology
+Parse optional flags from the request:
+- `--no-brace` — Skip BRACE build methodology (goals/build_app.md)
 - `--force` — Overwrite existing files without prompting
+
+---
+
+## Pre-flight
+
+Before starting, check all dependencies in this table:
+
+| Dependency | Type | Check | Required | Resolution | Detail |
+|-----------|------|-------|----------|------------|--------|
+| claude-mem | plugin | — | no | ask | `claude plugin install claude-mem` |
+
+For each row, in order:
+1. Run the Check command (for cli/npm) or test file existence (for agent/skill)
+2. If found: continue silently
+3. If missing: apply Resolution strategy
+   - **stop**: notify user with Detail, halt execution
+   - **url**: notify user with Detail (install link), halt execution
+   - **install**: notify user, run the command in Detail, continue if successful
+   - **ask**: notify user, offer to run command in Detail, continue either way (or halt if required)
+   - **fallback**: notify user with Detail, continue with degraded behavior
+4. After all checks: summarize what's available and what's degraded
+
+1. Capture **FLAGS** from the user's request
+2. Create a task list tracking all 5 phases
+
+---
+
+## Phase 1: Directory Scan
+
+Launch **Bash** subagent (**haiku**):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Scan directory for existing GOTCHA structure",
+  prompt: <read from references/phase-prompts.md#phase-1>
+)
+```
+
+Parse SCAN_REPORT. Extract:
+- `directory_name` (used as default project name)
+- `existing_dirs` / `missing_dirs`
+- `existing_files` / `missing_files`
+- `has_claude_md` / `has_gitignore`
+- `has_atlas` (legacy ATLAS naming detected)
+- `has_forge` (legacy FORGE naming detected)
+- `has_legacy_memory` (old tools/memory system detected)
+
+---
+
+## Phase 1b: Legacy Upgrade Detection
+
+**Skip if none of `has_atlas`, `has_forge`, or `has_legacy_memory` is true.**
+
+Build a description of what was found:
+- If `has_atlas` or `has_forge`: "Legacy ATLAS/FORGE naming detected"
+- If `has_legacy_memory`: "Legacy memory system (tools/memory/, memory/) detected"
+
+Ask the user via AskUserQuestion:
+
+   Question: "Legacy components detected: {description}. Upgrade and clean up?"
+   Options:
+   - "Yes, upgrade all" — Replace legacy naming with BRACE and remove old memory system
+   - "No, leave as-is" — Keep existing naming and memory system
+
+Store result as `upgrade_legacy: true|false` in USER_CONFIG.
+
+---
+
+## Phase 2: Project Inquiry
+
+**Runs on primary thread** (user interaction required).
+
+1. Derive default project name from SCAN_REPORT `directory_name`
+2. Present via AskUserQuestion:
+
+   Question: "What to include in GOTCHA setup?"
+   Options:
+   - "Full GOTCHA + BRACE (Recommended)"
+   - "GOTCHA structure only (no BRACE methodology)"
+   - "Cancel"
+
+3. If not cancelled, ask for project description (one sentence) via
+   AskUserQuestion with free text.
+
+4. Ask installation level via AskUserQuestion:
+
+   Question: "Where should global preferences and universal principles go?"
+   Options:
+   - "Both — global + project (Recommended)" → portable AND global coverage
+   - "Global (~/.claude/CLAUDE.md) only" → applies to all projects
+   - "Project level only" → self-contained, portable
+
+5. Store as USER_CONFIG:
+   - project_name: from directory name or user override
+   - description: from user input
+   - include_brace: true/false (based on selection and `--no-brace`)
+   - install_level: "both" | "global" | "project"
+
+**If cancelled, stop here.**
+
+---
+
+## Phase 3: Present Plan & Approve
+
+Build the ACTION_PLAN from SCAN_REPORT + USER_CONFIG + FLAGS.
+
+For each item in `references/scaffold-manifest.md`:
+- If component not selected in USER_CONFIG → status: "not selected"
+- If item already exists (from SCAN_REPORT) and no `--force` → status: "skip"
+- If item exists and `--force` → status: "overwrite"
+- If CLAUDE.md exists → status: "merge" (append GOTCHA section)
+- If .gitignore exists → status: "merge" (append missing entries)
+- Otherwise → status: "create"
+
+If `upgrade_legacy` is true in USER_CONFIG, set status "upgrade" for:
+- CLAUDE.md (replaces "merge" or "skip" — upgrade takes priority)
+- goals/build_app.md (replaces "skip")
+- goals/manifest.md (replaces "skip")
+
+If `upgrade_legacy` is true AND `has_legacy_memory` is true, additionally:
+- `tools/memory/` → status: "remove"
+- `memory/` → status: "remove"
+- CLAUDE.md also gets memory section replacement (handled alongside upgrade)
+- `tools/manifest.md` → status: "cleanup" (remove memory tool rows)
+- `.gitignore` → status: "cleanup" (remove memory/*.npy entry)
+
+Present plan summary to user via AskUserQuestion:
+
+```
+GOTCHA Framework Setup for: {project_name}
+
+Will create:  {list of items with status "create"}
+Will merge:   {list of items with status "merge"}
+Will upgrade: {list of items with status "upgrade" — legacy → BRACE}
+Will remove:  {list of items with status "remove" — legacy memory system}
+Will clean:   {list of items with status "cleanup" — remove legacy references}
+Will skip:    {count} existing items
+Not selected: {count} items
+Global config: {install_level description}
+
+Proceed?
+```
+
+Options: "Yes, proceed" / "Cancel"
+
+**If cancelled, stop here.**
+
+---
+
+## Phase 4: Scaffold Structure
+
+Launch **general-purpose** subagent:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Create GOTCHA framework structure",
+  prompt: <read from references/phase-prompts.md#phase-4>
+)
+```
+
+Before sending the prompt, substitute these variables:
+- `{ACTION_PLAN}` — the action plan from Phase 3
+- `{PROJECT_NAME}` — from USER_CONFIG
+- `{PROJECT_DESCRIPTION}` — from USER_CONFIG
+- `{INSTALL_LEVEL}` — from USER_CONFIG ("both", "global", or "project")
+- `{CLAUDE_MD_TEMPLATE}` — read from `references/claude-md-template.md`
+  (the section between BEGIN TEMPLATE and END TEMPLATE)
+- `{GITIGNORE_CONTENT}` — read from `assets/gitignore-template`
+- `{GOALS_MANIFEST}` — read from `references/scaffold-manifest.md`
+  (the goals/manifest.md content block)
+- `{TOOLS_MANIFEST}` — read from `references/scaffold-manifest.md`
+  (the tools/manifest.md content block)
+- `{BRACE_WORKFLOW}` — read from `references/brace-workflow.md`
+  (the section after the header, used for goals/build_app.md)
+- `{GLOBAL_PREFERENCES_CONTENT}` — read from `assets/global-preferences-template.md`
+  (the section between BEGIN TEMPLATE and END TEMPLATE)
+
+Parse SCAFFOLD_REPORT. If status is "failed", report to user and stop.
+
+---
+
+## Phase 5: Verification & Report
+
+Launch **Bash** subagent (**haiku**):
+
+```
+Task(
+  subagent_type: "Bash",
+  model: "haiku",
+  description: "Verify GOTCHA structure",
+  prompt: <read from references/phase-prompts.md#phase-5>
+)
+```
+
+Parse VERIFY_REPORT. Present the final summary using the format in
+`references/report-template.md`.
+
+---
+
+## Idempotency Rules
+
+- **Skip** directories and files that already exist (unless `--force`)
+- **Merge** CLAUDE.md: append GOTCHA section if file exists but lacks it
+- **Merge** .gitignore: append missing entries only
+- **Never delete** user content
+- **Never overwrite** without `--force` or explicit user approval
+
+---
+
+## Error Handling
+
+Standard escalation pattern:
+1. If retryable (permission issue after mkdir): retry once
+2. If persistent: report to user with specific error
+3. Offer: skip and continue / abort
+4. Never silently swallow errors
+
+Common issues:
+- Permission denied → report, suggest checking directory permissions
+- CLAUDE.md merge conflict → show both versions, let user choose
+- Directory is read-only → abort with clear message

package/skills/brace/assets/gitignore-template

@@ -15,9 +15,6 @@ data/
 # Temp & scratch
 .tmp/
 
-# Memory embeddings cache
-memory/*.npy
-
 # Python
 __pycache__/
 *.pyc

package/skills/brace/references/phase-prompts.md

@@ -47,6 +47,12 @@ Limit your SCAN_REPORT to 20 lines maximum.
      fi
    done
 
+7. Check for legacy memory system:
+   legacy_memory=false
+   if [ -d "tools/memory" ] || [ -f "memory/MEMORY.md" ]; then
+     legacy_memory=true
+   fi
+
 ## Output Format
 
 SCAN_REPORT:
@@ -60,6 +66,7 @@ SCAN_REPORT:
   has_gitignore: true|false
   has_atlas: true|false
   has_forge: true|false
+  has_legacy_memory: true|false
 ```
 
 ---
@@ -114,6 +121,25 @@ legacy methodology references with BRACE equivalents while preserving all other
 - **goals/build_app.md:** Replace the entire file with the BRACE workflow content below.
 - **goals/manifest.md:** Replace "ATLAS" or "FORGE" with "BRACE" in the description column.
 
+### For "remove" items (legacy memory cleanup):
+
+1. Before deleting `memory/MEMORY.md`, check if it contains a "## Key Decisions"
+   section. If so, extract that section content into `preserved_content` for the
+   SCAFFOLD_REPORT so the user can relocate it.
+2. Remove `tools/memory/` — use `git rm -r tools/memory` if tracked, otherwise `rm -rf tools/memory`
+3. Remove `memory/` — use `git rm -r memory` if tracked, otherwise `rm -rf memory`
+
+### For "cleanup" items (legacy memory references):
+
+- **tools/manifest.md:** Remove any rows referencing `memory/` tools (e.g. search, embed, store scripts)
+- **.gitignore:** Remove the `memory/*.npy` line and its `# Memory embeddings cache` comment if present
+- **CLAUDE.md:** If a `## Memory System` section exists, replace it with:
+  ```
+  ## Memory
+  This project uses claude-mem for persistent cross-session memory.
+  ```
+  Also remove `tools/memory/` and `memory/` from any directory tree listings in CLAUDE.md.
+
 ### Global preferences (conditional)
 
 If INSTALL_LEVEL is "global" or "both":
@@ -178,6 +204,9 @@ SCAFFOLD_REPORT:
   created: [list of files/dirs created]
   merged: [list of files merged]
   upgraded: [list of files upgraded to BRACE]
+  removed: [list of legacy items removed]
+  cleaned: [list of files cleaned of legacy references]
+  preserved_content: [any key decisions extracted from memory/MEMORY.md, or empty]
   skipped: [list of items skipped]
   global_updated: true|false|skipped
   errors: [any errors encountered]
@@ -216,6 +245,13 @@ Limit your VERIFY_REPORT to 15 lines maximum.
    done
    echo "gitignore entries: $entries/2"
 
+5. If legacy memory cleanup was performed, verify removal:
+   if [ -d "tools/memory" ]; then echo "legacy: tools/memory still exists"; fi
+   if [ -d "memory" ]; then echo "legacy: memory/ still exists"; fi
+   if [ -f "CLAUDE.md" ] && grep -q "tools/memory" CLAUDE.md; then
+     echo "legacy: CLAUDE.md still references tools/memory"
+   fi
+
 ## Output Format
 
 VERIFY_REPORT:
@@ -224,5 +260,6 @@ VERIFY_REPORT:
   files_verified: {count}/{expected}
   claude_md_has_gotcha: true|false
   gitignore_entries: {count}/{expected}
+  legacy_memory_cleaned: true|false|not_applicable
   issues: [any problems found]
 ```

package/skills/brace/references/report-template.md

@@ -25,6 +25,10 @@ Brace Complete!
     {status} goals/build_app.md
     {status} tools/manifest.md
 
+  Removed: (only if legacy memory was cleaned up)
+    {status} tools/memory/     Legacy memory scripts
+    {status} memory/           Legacy memory directory
+
   Notes:
     {any warnings or skipped items}
 
@@ -35,4 +39,4 @@ Brace Complete!
     4. Start building with the BRACE methodology
 ```
 
-Status indicators: [created] [exists] [merged] [upgraded] [skipped] [failed]
+Status indicators: [created] [exists] [merged] [upgraded] [removed] [skipped] [failed]