@slamb2k/mad-skills 2.0.6

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

@@ -0,0 +1,91 @@
+# CLAUDE.md Template
+
+Template for the generated project CLAUDE.md. The Phase 4 agent substitutes
+`{VARIABLE}` placeholders and writes to the project root.
+
+`{UNIVERSAL_PRINCIPLES}` is populated with the Question & Assumption
+Accountability and Communication sections when install_level is "project"
+or "both". Left empty when install_level is "global" (principles are in
+`~/.claude/CLAUDE.md` instead).
+
+---
+
+BEGIN TEMPLATE
+
+# {PROJECT_NAME}
+
+{PROJECT_DESCRIPTION}
+
+## Operating Framework: GOTCHA
+
+This project uses the **GOTCHA Framework** — a 6-layer architecture for
+agentic AI systems. LLMs handle reasoning; deterministic tools handle execution.
+
+**GOT** (The Engine):
+- **Goals** (`goals/`) — Process definitions. Check `goals/manifest.md` first.
+- **Orchestration** — You (the AI). Read goals, delegate to tools, handle errors.
+- **Tools** (`tools/`) — Python scripts. Check `tools/manifest.md` first.
+
+**CHA** (The Context):
+- **Context** (`context/`) — Domain knowledge, reference material
+- **Hard Prompts** (`hardprompts/`) — Reusable instruction templates
+- **Args** (`args/`) — Behaviour settings (YAML/JSON)
+
+### Operating Rules
+
+1. **Check goals first** — Before any task, read `goals/manifest.md`
+2. **Check tools first** — Before writing code, read `tools/manifest.md`
+3. **Fix and document** — When tools fail, fix them and update the goal
+4. **Never modify goals without permission** — Goals are living documentation
+5. **Communicate when stuck** — Explain what is missing, do not guess
+
+## Directory Structure
+
+```
+{PROJECT_NAME}/
+├── CLAUDE.md           This file
+├── .gitignore          Ignores credentials, data, temp files
+├── goals/              Process definitions
+│   ├── manifest.md     Index of all goals
+│   └── build_app.md    BRACE build methodology
+├── tools/              Deterministic scripts
+│   └── manifest.md     Index of all tools
+├── context/            Domain knowledge and references
+├── hardprompts/        Reusable LLM instruction templates
+├── args/               Behaviour settings (YAML/JSON)
+└── .tmp/               Scratch work (gitignored)
+```
+
+## Memory
+
+For persistent memory across sessions, install the **claude-mem** plugin:
+```
+claude plugin install claude-mem
+```
+
+claude-mem automatically captures context via lifecycle hooks and provides
+MCP tools for search, timeline, and observation management. Claude Code's
+built-in auto memory (`~/.claude/projects/<project>/memory/MEMORY.md`)
+handles curated facts.
+
+## Build Methodology: BRACE
+
+See `goals/build_app.md` for the full workflow:
+- **B**rief — Define problem, users, success metrics
+- **R**esearch — Data schema, integrations, stack proposal
+- **A**rchitect — Design structure, validate all connections
+- **C**onstruct — Build DB first, then API, then UI
+- **E**valuate — Functional, integration, edge case, acceptance testing
+
+{UNIVERSAL_PRINCIPLES}
+
+## Guardrails
+
+- Always check manifests before creating new goals or tools
+- Verify tool output format before chaining into another tool
+- Do not assume APIs support batch operations — check first
+- Preserve intermediate outputs when workflows fail mid-execution
+- Read the full goal before starting — do not skim
+- Temporary files go in `.tmp/` — never store important data there
+
+END TEMPLATE

package/skills/brace/references/gotcha-principles.md

@@ -0,0 +1,113 @@
+# GOTCHA Framework Principles
+
+Embedded into the project CLAUDE.md during brace.
+
+---
+
+## The GOTCHA Framework
+
+A 6-layer architecture for agentic systems that separates concerns between
+probabilistic reasoning (LLM) and deterministic execution (tools).
+
+**GOT** (The Engine):
+- **Goals** (`goals/`) — Task-specific instructions. Each goal defines:
+  objective, inputs, which tools to use, expected outputs, edge cases.
+  Only modified with explicit permission.
+- **Orchestration** — The AI manager (you). Reads goals, decides which tools
+  to use, applies args, references context, handles errors, delegates work.
+  Never executes work directly — delegates intelligently.
+- **Tools** (`tools/`) — Python scripts organised by workflow. Each has one
+  job: API calls, data processing, file operations, database work. Fast,
+  documented, testable, deterministic. All tools listed in `tools/manifest.md`.
+
+**CHA** (The Context):
+- **Context** (`context/`) — Static reference material: tone rules, writing
+  samples, ICP descriptions, case studies. Shapes quality/style, not process.
+- **Hard Prompts** (`hardprompts/`) — Reusable text templates for LLM
+  sub-tasks: outline-to-post, rewrite-in-voice, summarize-transcript.
+- **Args** (`args/`) — YAML/JSON files controlling behaviour: themes,
+  frameworks, modes, lengths, schedules, model choices. Changing args changes
+  behaviour without editing goals or tools.
+
+## How to Operate
+
+### 1. Check for existing goals first
+Before starting a task, check `goals/manifest.md`. If a goal exists, follow
+it — goals define the full process for common tasks.
+
+### 2. Check for existing tools
+Before writing new code, read `tools/manifest.md`. If a tool exists, use it.
+If you create a new tool, you **must** add it to the manifest.
+
+### 3. When tools fail, fix and document
+- Read the error and stack trace carefully
+- Update the tool to handle the issue
+- Add what you learned to the goal
+- If a goal gets too long, split into primary goal + technical reference
+
+### 4. Treat goals as living documentation
+- Update only when better approaches or API constraints emerge
+- Never modify/create goals without explicit permission
+
+### 5. Communicate clearly when stuck
+If you cannot complete a task with existing tools and goals:
+- Explain what is missing
+- Explain what you need
+- Do not guess or invent capabilities
+
+### 6. Guardrails
+- Always check `tools/manifest.md` before writing a new script
+- Verify tool output format before chaining into another tool
+- Do not assume APIs support batch operations — check first
+- When a workflow fails mid-execution, preserve intermediate outputs
+- Read the full goal before starting a task — do not skim
+
+## Memory
+
+For persistent memory across sessions, use the **claude-mem** plugin
+(`claude plugin install claude-mem`). It automatically captures context
+via lifecycle hooks and provides MCP tools for search, timeline, and
+observation management. Claude Code's built-in auto memory handles
+curated facts (`~/.claude/projects/<project>/memory/MEMORY.md`).
+
+## Question & Assumption Accountability
+
+Nothing gets silently dropped. Every open question, assumption, and deferred
+decision must be explicitly recorded and revisited.
+
+### During work:
+- When you make an assumption, **state it explicitly** and record it
+- When a question cannot be answered immediately, log it as an open item
+- When you defer a fix or skip an edge case, document why and what triggers it
+
+### At the end of each task:
+- Review all assumptions made — were they validated?
+- Review all open questions — were they answered?
+- Review all deferred items — are they tracked for follow-up?
+- Present unresolved items to the user with context and suggested actions
+
+### Persistence:
+- Unresolved items go to `goals/` as documented follow-ups, to CLAUDE.md
+  as "Known Issues", or to memory for future session awareness
+- Never close a task with unacknowledged open questions
+- At the start of new work, check for outstanding items from previous sessions
+
+### Why this matters:
+90% accuracy per step means ~59% accuracy over 5 steps. Silent assumptions
+compound. Explicit tracking breaks the chain — each assumption is either
+validated or flagged before it can propagate.
+
+## The Continuous Improvement Loop
+
+Every failure strengthens the system:
+1. Identify what broke and why
+2. Fix the tool script
+3. Test until it works reliably
+4. Update the goal with new knowledge
+5. Next time — automatic success
+
+## Deliverables vs Scratch
+
+- **Deliverables**: outputs needed by the user (processed data, reports, etc.)
+- **Scratch work**: temp files (raw scrapes, CSVs, research). Always disposable.
+- Never store important data in `.tmp/`

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

@@ -0,0 +1,228 @@
+# Brace Phase Prompts
+
+Subagent prompts for each phase. The orchestrator reads the relevant section
+and substitutes `{VARIABLE}` placeholders before sending to the subagent.
+
+---
+
+## Phase 1: Directory Scan
+
+**Agent:** Bash | **Model:** haiku
+
+```
+Scan the current working directory for existing GOTCHA/BRACE framework structure.
+
+Limit your SCAN_REPORT to 20 lines maximum.
+
+## Checks
+
+1. Check for each GOTCHA directory:
+   goals/ tools/ context/ hardprompts/ args/ .tmp/
+
+2. Check for each key file:
+   CLAUDE.md .gitignore goals/manifest.md goals/build_app.md
+   tools/manifest.md
+
+3. Check if directory is a git repo:
+   [ -d .git ] && echo "git: true" || echo "git: false"
+
+4. Get directory name:
+   basename "$(pwd)"
+
+5. Check for legacy ATLAS references:
+   atlas_found=false
+   for f in CLAUDE.md goals/build_app.md goals/manifest.md; do
+     if [ -f "$f" ] && grep -qi "ATLAS" "$f"; then
+       atlas_found=true
+       break
+     fi
+   done
+
+6. Check for legacy FORGE references:
+   forge_found=false
+   for f in CLAUDE.md goals/build_app.md goals/manifest.md; do
+     if [ -f "$f" ] && grep -qi "FORGE" "$f"; then
+       forge_found=true
+       break
+     fi
+   done
+
+## Output Format
+
+SCAN_REPORT:
+  directory_name: {name}
+  git_initialized: true|false
+  existing_dirs: [comma-separated list]
+  existing_files: [comma-separated list]
+  missing_dirs: [comma-separated list]
+  missing_files: [comma-separated list]
+  has_claude_md: true|false
+  has_gitignore: true|false
+  has_atlas: true|false
+  has_forge: true|false
+```
+
+---
+
+## Phase 4: Scaffold Structure
+
+**Agent:** general-purpose | **Model:** default
+
+```
+Create the GOTCHA/BRACE framework structure in the current directory.
+
+Limit your SCAFFOLD_REPORT to 15 lines maximum.
+
+## Inputs
+
+- ACTION_PLAN: {ACTION_PLAN}
+- PROJECT_NAME: {PROJECT_NAME}
+- PROJECT_DESCRIPTION: {PROJECT_DESCRIPTION}
+- INSTALL_LEVEL: {INSTALL_LEVEL}
+
+## Instructions
+
+Only act on items in the ACTION_PLAN with status "create", "merge", or "upgrade".
+Skip items with status "skip" or "not selected".
+
+### For "create" items:
+
+1. Create directories with mkdir -p
+2. Create .gitkeep in empty directories (context/, hardprompts/, args/, .tmp/)
+3. Write CLAUDE.md using the template below, substituting {PROJECT_NAME},
+   {PROJECT_DESCRIPTION}, and {UNIVERSAL_PRINCIPLES}
+4. Write .gitignore from the content below
+5. Write goals/manifest.md and tools/manifest.md from content below
+6. Write goals/build_app.md from the BRACE workflow content below
+
+### For "merge" items:
+
+- CLAUDE.md: Read existing file. If it does not contain "GOTCHA", append
+  the GOTCHA section from the template. If it does, skip.
+- .gitignore: Read existing file. Append any missing entries from the
+  template. Do not duplicate existing entries.
+
+### For "upgrade" items (legacy → BRACE migration):
+
+These files already exist but contain legacy ATLAS or FORGE naming. Replace the
+legacy methodology references with BRACE equivalents while preserving all other content.
+
+- **CLAUDE.md:** Replace the "Build Methodology: ATLAS" or "Build Methodology: FORGE"
+  section (from that heading through the bullet list) with the BRACE section from
+  the template. Also replace "ATLAS build methodology" or "FORGE build methodology"
+  with "BRACE build methodology" in the directory tree comment. Preserve all other sections.
+- **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.
+
+### Global preferences (conditional)
+
+If INSTALL_LEVEL is "global" or "both":
+- Read ~/.claude/CLAUDE.md
+- If it does NOT contain "## Global Preferences", insert the Global
+  Preferences Content (below) immediately before "## Current Skills"
+- If it already contains "## Global Preferences", skip (idempotent)
+
+### {UNIVERSAL_PRINCIPLES} substitution
+
+If INSTALL_LEVEL is "project" or "both", substitute {UNIVERSAL_PRINCIPLES}
+in the CLAUDE.md template with the Universal Principles Content below.
+
+If INSTALL_LEVEL is "global", substitute {UNIVERSAL_PRINCIPLES} with an
+empty string (principles are in the global config instead).
+
+### CLAUDE.md Template
+
+{CLAUDE_MD_TEMPLATE}
+
+### .gitignore Content
+
+{GITIGNORE_CONTENT}
+
+### goals/manifest.md Content
+
+{GOALS_MANIFEST}
+
+### tools/manifest.md Content
+
+{TOOLS_MANIFEST}
+
+### goals/build_app.md Content
+
+{BRACE_WORKFLOW}
+
+### Global Preferences Content
+
+{GLOBAL_PREFERENCES_CONTENT}
+
+### Universal Principles Content
+
+## Question & Assumption Accountability
+
+Nothing gets silently dropped. Every open question, assumption, and deferred
+decision must be explicitly recorded and revisited.
+
+- When you make an assumption, **state it explicitly** and record it
+- When a question cannot be answered immediately, log it as an open item
+- When you defer a fix or skip an edge case, document why and what triggers it
+- At the end of each task, review all assumptions and open questions
+- Present unresolved items to the user with context and suggested actions
+- Unresolved items go to `goals/` as follow-ups, to CLAUDE.md as "Known Issues",
+  or to memory for future session awareness
+- At the start of new work, check for outstanding items from previous sessions
+- Never close a task with unacknowledged open questions
+
+## Output Format
+
+SCAFFOLD_REPORT:
+  status: success|partial|failed
+  created: [list of files/dirs created]
+  merged: [list of files merged]
+  upgraded: [list of files upgraded to BRACE]
+  skipped: [list of items skipped]
+  global_updated: true|false|skipped
+  errors: [any errors encountered]
+```
+
+---
+
+## Phase 5: Verification
+
+**Agent:** Bash | **Model:** haiku
+
+```
+Verify the GOTCHA framework was initialised correctly.
+
+Limit your VERIFY_REPORT to 15 lines maximum.
+
+## Checks
+
+1. Verify expected directories exist:
+   for d in goals tools context hardprompts args .tmp; do
+     [ -d "$d" ] && echo "dir ok: $d" || echo "dir MISSING: $d"
+   done
+
+2. Verify key files exist and are non-empty:
+   for f in CLAUDE.md .gitignore goals/manifest.md tools/manifest.md; do
+     [ -s "$f" ] && echo "file ok: $f" || echo "file MISSING: $f"
+   done
+
+3. Check CLAUDE.md contains GOTCHA reference:
+   grep -q "GOTCHA" CLAUDE.md && echo "claude_md: has GOTCHA" || echo "claude_md: no GOTCHA"
+
+4. Check .gitignore has key entries:
+   entries=0
+   for pattern in ".env" ".tmp/"; do
+     grep -q "$pattern" .gitignore && entries=$((entries+1))
+   done
+   echo "gitignore entries: $entries/2"
+
+## Output Format
+
+VERIFY_REPORT:
+  status: complete|partial|failed
+  dirs_verified: {count}/{expected}
+  files_verified: {count}/{expected}
+  claude_md_has_gotcha: true|false
+  gitignore_entries: {count}/{expected}
+  issues: [any problems found]
+```

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

@@ -0,0 +1,38 @@
+# Brace Report Template
+
+Present this summary after verification completes.
+
+---
+
+```
+Brace Complete!
+
+  Project:   {project_name}
+  Directory: {cwd}
+
+  Structure:
+    {status} goals/         Goals layer
+    {status} tools/         Tools layer
+    {status} context/       Context layer
+    {status} hardprompts/   Hard prompts layer
+    {status} args/          Args layer
+    {status} .tmp/          Temp directory
+
+  Files:
+    {status} CLAUDE.md
+    {status} .gitignore
+    {status} goals/manifest.md
+    {status} goals/build_app.md
+    {status} tools/manifest.md
+
+  Notes:
+    {any warnings or skipped items}
+
+  Next steps:
+    1. Review CLAUDE.md and customise for your project
+    2. Add domain knowledge to context/
+    3. Define your first goal in goals/
+    4. Start building with the BRACE methodology
+```
+
+Status indicators: [created] [exists] [merged] [upgraded] [skipped] [failed]

package/skills/brace/references/scaffold-manifest.md

@@ -0,0 +1,68 @@
+# Scaffold Manifest
+
+Everything brace creates, grouped by component. Phase 4 uses this as its
+creation checklist. Phase 1 uses it to detect existing structure.
+
+## Core Files
+
+| File | Source | Description |
+|------|--------|-------------|
+| `CLAUDE.md` | references/claude-md-template.md | Project operating document |
+| `.gitignore` | assets/gitignore-template | Standard ignores |
+| `~/.claude/CLAUDE.md` | assets/global-preferences-template.md | Global preferences (conditional on install_level) |
+
+## Goals Layer
+
+| Path | Source | Description |
+|------|--------|-------------|
+| `goals/` | mkdir | Process definitions directory |
+| `goals/manifest.md` | generated | Index of all goal workflows |
+| `goals/build_app.md` | references/brace-workflow.md | BRACE build methodology |
+
+## Tools Layer
+
+| Path | Source | Description |
+|------|--------|-------------|
+| `tools/` | mkdir | Deterministic scripts directory |
+| `tools/manifest.md` | generated | Index of all tools |
+
+## Context, Hard Prompts, Args Layers
+
+| Path | Description |
+|------|-------------|
+| `context/` | Reference material and domain knowledge |
+| `hardprompts/` | Reusable instruction templates |
+| `args/` | Behaviour settings (YAML/JSON) |
+
+## Temp
+
+| Path | Description |
+|------|-------------|
+| `.tmp/` | Scratch work (gitignored) |
+
+## Generated Manifest Content
+
+### goals/manifest.md
+```
+# Goals Manifest
+
+Index of all goal workflows in this project.
+
+| Goal | File | Description |
+|------|------|-------------|
+| Build App | build_app.md | BRACE 5-step build methodology |
+
+Add new goals here as they are created.
+```
+
+### tools/manifest.md
+```
+# Tools Manifest
+
+Index of all tools in this project.
+
+| Tool | Path | Description |
+|------|------|-------------|
+
+Add new tools here as they are created.
+```

package/skills/brace/tests/evals.json

@@ -0,0 +1,29 @@
+[
+  {
+    "name": "banner-and-tagline",
+    "prompt": "Initialize GOTCHA framework for this project",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "regex", "value": "(Bracing the|Reinforcing before|Locking in the|Preparing for heavy|Cross-bracing|Tightening the load|Structural integrity|Brace for impact)" },
+      { "type": "semantic", "value": "The response begins with an ASCII art banner displayed BEFORE any explanation or workflow steps" }
+    ]
+  },
+  {
+    "name": "gotcha-framework",
+    "prompt": "Set up the GOTCHA structure in my project",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "regex", "value": "GOTCHA", "flags": "i" },
+      { "type": "regex", "value": "(Goals|Orchestration|Tools|Context)", "flags": "i" },
+      { "type": "semantic", "value": "Describes the GOTCHA framework with its 6-layer structure: Goals, Orchestration, Tools, Context, Hard prompts, and Args" }
+    ]
+  },
+  {
+    "name": "flag-handling",
+    "prompt": "Brace --no-brace this project directory",
+    "assertions": [
+      { "type": "contains", "value": "██" },
+      { "type": "semantic", "value": "Acknowledges the --no-brace flag, indicating it will skip the BRACE build methodology while still creating the GOTCHA directory structure" }
+    ]
+  }
+]

package/skills/build/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: build
+description: >
+  Context-isolated feature development pipeline. Takes a detailed design/plan
+  as argument and executes the full feature-dev lifecycle (explore, question,
+  architect, implement, review, ship) inside subagents so the primary
+  conversation stays compact. Use when you have a well-defined plan and want
+  autonomous execution with minimal context window consumption.
+argument-hint: Detailed design/plan to implement
+---
+
+# Build - Context-Isolated Feature Development
+
+When this skill is invoked, IMMEDIATELY output the banner below before doing anything else.
+Pick ONE tagline at random — vary your choice each time:
+
+```
+{tagline}
+
+    ██╗██████╗ ██╗   ██╗██╗██╗     ██████╗
+   ██╔╝██╔══██╗██║   ██║██║██║     ██╔══██╗
+  ██╔╝ ██████╔╝██║   ██║██║██║     ██║  ██║
+ ██╔╝  ██╔══██╗██║   ██║██║██║     ██║  ██║
+██╔╝   ██████╔╝╚██████╔╝██║███████╗██████╔╝
+╚═╝    ╚═════╝  ╚═════╝ ╚═╝╚══════╝╚═════╝
+
+```
+
+Taglines:
+- ⚙️ Compiling hopes and dreams...
+- 🏗️ Bob the Builder has entered the chat!
+- 🤖 Assembling the Voltron of code!
+- 🏭 Feature factory: ONLINE
+- ☕ Hold my coffee, I'm building!
+- 📦 Some assembly required...
+- 🧱 Bricks, mortar, and semicolons!
+- 🏎️ Let's see what this baby can do!
+
+Follow instructions in: [instructions.md](instructions.md)
+
+Architecture, agent types, and report budgets are documented in `references/`.
+
+## Flags
+
+- `--skip-questions`: Skip clarifying questions (plan is fully specified)
+- `--skip-review`: Skip code review stage
+- `--no-ship`: Stop after docs update (don't commit/push/PR)
+- `--parallel-impl`: Allow parallel implementation agents