@accelerationguy/accel 1.0.0

package/modules/forge/specs/frameworks.md

@@ -0,0 +1,228 @@
+# Frameworks Syntax Spec
+
+Defines the syntax for framework files: `frameworks/*.md` — read-only reference knowledge loaded by tasks when domain context is needed.
+
+**Applies to:** `skills/{skill-name}/frameworks/*.md`
+
+---
+
+## No Frontmatter
+
+Frameworks do not use YAML frontmatter. They are conceptual knowledge, not executable artifacts. Content starts immediately.
+
+---
+
+## File Structure
+
+Frameworks follow a teaching-oriented structure:
+
+1. **Outer XML container** (optional) — Semantic tag matching the concept
+2. **Purpose section** — What this framework explains
+3. **Core concepts** — The knowledge itself, organized by topic
+4. **Examples** — Concrete illustrations (good vs bad when applicable)
+5. **Anti-patterns** — What to avoid and WHY
+6. **Sources** (optional) — Attribution if from a book, course, or methodology
+
+---
+
+## Outer XML Container
+
+Frameworks may use an outer XML container related to their topic. Not required, but adds semantic clarity for parseable sections.
+
+```xml
+<!-- hormozi-value-equation.md -->
+<value_equation>
+## Purpose
+...
+
+## The Four Variables
+...
+</value_equation>
+
+<!-- hook-patterns.md -->
+<hook_patterns>
+## Purpose
+...
+
+## Pattern Types
+...
+</hook_patterns>
+```
+
+**Tag naming:** snake_case matching the concept. Use when the framework has distinct parseable sections a task might reference individually.
+
+---
+
+## Teaching Patterns
+
+Frameworks explain domain knowledge for tasks to consume. Two primary teaching patterns:
+
+### Teach by Contrast
+
+Show good vs bad to make principles concrete:
+
+```markdown
+## Weak vs Strong Dream Outcomes
+
+**Weak:** "Grow your business"
+- Not specific, not measurable, not compelling
+
+**Strong:** "Generate 20 qualified leads per month without cold calling"
+- Specific number, specific method, specific relief
+```
+
+### Explain WHY
+
+Don't just state rules — explain the reasoning:
+
+```markdown
+## Why Price Anchoring Matters
+
+Without anchoring, customers compare your price to competitors.
+With anchoring, customers compare your price to the VALUE they receive.
+
+A $5,000 offer feels expensive compared to a $2,000 competitor.
+A $5,000 offer feels like a steal compared to $50,000 in delivered value.
+
+The anchor shifts the reference point from cost to value.
+```
+
+---
+
+## Loading Pattern
+
+Frameworks are lazy-loaded by tasks when conceptual context is needed:
+
+```xml
+<!-- In a task file -->
+<references>
+@frameworks/hormozi-value-equation.md (during pricing step)
+@frameworks/risk-reversal-patterns.md (during guarantee step)
+</references>
+```
+
+**Rules:**
+- Frameworks are loaded on demand, not pre-loaded at skill activation
+- A task can load one framework without needing others (self-contained)
+- Entry point `<routing>` lists frameworks under "Load on Demand"
+
+---
+
+## Distinction: Frameworks vs Context vs Templates
+
+| Type | Purpose | Mutability | Loaded When |
+|------|---------|------------|-------------|
+| **Frameworks** | Domain knowledge (concepts, methods, patterns) | Read-only — never modified | On demand by tasks |
+| **Context** | Business/user state (profiles, preferences, history) | Mutable — updated as context changes | On skill activation |
+| **Templates** | Output structure (fill-in-the-blank formats) | Read-only — output written elsewhere | During task output generation |
+
+**Rule of thumb:**
+- If it teaches a concept → framework
+- If it describes a specific user/business → context
+- If it defines output shape → template
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Framework file | kebab-case, descriptive | `hormozi-value-equation.md`, `hook-patterns.md` |
+| Directory | Always `frameworks/` | `skills/revops-expert/frameworks/` |
+| Outer XML tag | snake_case | `<value_equation>`, `<hook_patterns>` |
+
+---
+
+## Core Principle
+
+**Frameworks are knowledge, not instructions.** They explain concepts and patterns that tasks reference when making decisions or generating output.
+
+Frameworks are self-contained — loading one framework should never require loading another. If two concepts are tightly coupled, they belong in the same file.
+
+---
+
+## Good vs Bad Examples
+
+### Good: Teaching-Oriented Framework
+
+```xml
+<value_equation>
+
+## Purpose
+
+Alex Hormozi's Value Equation from "$100M Offers." Quantifies offer value using four variables. Used during offer design to ensure compelling pricing.
+
+## The Equation
+
+```
+Value = (Dream Outcome × Perceived Likelihood) / (Time Delay × Effort & Sacrifice)
+```
+
+Maximize the top (outcome, believability). Minimize the bottom (time, effort).
+
+## Variables
+
+### Dream Outcome
+The ideal result your customer achieves.
+
+**Strong:** "Generate 20 qualified leads per month without cold calling"
+**Weak:** "Grow your business" (vague, not measurable)
+
+### Perceived Likelihood of Achievement
+Why the customer believes this will work FOR THEM.
+
+**Elements:** Case studies, credentials, specificity of method, guarantees.
+
+### Time Delay
+How long until they see results. Shorter = more valuable.
+
+**Strong:** "First leads within 14 days"
+**Weak:** "Results over time"
+
+### Effort & Sacrifice
+What the customer DOESN'T have to do. Less effort = more valuable.
+
+**Strong:** "Done-for-you setup, no technical skills needed"
+**Weak:** "Easy to use" (subjective, unspecific)
+
+## Anti-Patterns
+
+| Anti-Pattern | Fix |
+|-------------|-----|
+| Pricing based on cost, not value | Anchor to dream outcome dollar value |
+| Vague dream outcomes | Make specific and measurable |
+| No proof elements | Add case studies, guarantees, credentials |
+| Ignoring effort reduction | Explicitly list what customer doesn't do |
+
+## Source
+
+Alex Hormozi, "$100M Offers" (2021)
+
+</value_equation>
+```
+
+### Bad: Vague Framework
+
+```markdown
+# Value Equation
+
+The value equation helps you price offers.
+
+You should think about what the customer gets and how much effort it takes.
+Price your offer based on value.
+```
+
+**Why bad:** No structure, no variables explained, no examples, no contrast, nothing actionable. A task loading this framework gains nothing.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Framework with instructions | Frameworks teach, they don't instruct — that's tasks | Move step-by-step instructions to `tasks/` |
+| Framework requiring other frameworks | Breaks self-contained principle | Merge coupled concepts into one file |
+| No examples | Abstract knowledge without concrete illustration | Add good/bad contrast examples |
+| No "WHY" explanations | Rules without reasoning are hard to apply | Explain the principle behind each concept |
+| Modifying frameworks during execution | Breaks read-only contract | Frameworks are immutable reference — write output elsewhere |
+| Loading all frameworks at activation | Wastes context on irrelevant knowledge | Lazy-load from tasks when needed |

package/modules/forge/specs/rules.md

@@ -0,0 +1,245 @@
+# Rules Syntax Spec
+
+Defines the syntax for rule files: `rules/*.md` — authoring rules that define what every file of a given type must contain.
+
+**Applies to:** Meta-skill only (`skills/forge/rules/*.md`). Individual skills do NOT carry their own rules.
+
+---
+
+## YAML Frontmatter
+
+Rules files use YAML frontmatter with a `paths:` field targeting the folder type they govern:
+
+```yaml
+---
+paths:
+  - "skills/*/tasks/**/*.md"
+---
+```
+
+### Frontmatter Fields
+
+| Field | Required | Purpose | Example |
+|-------|----------|---------|---------|
+| `paths` | Yes | Glob patterns for files this rule applies to | `["skills/*/entry-point.md"]` |
+
+The `paths` field tells tooling which files to validate against this rule. Use glob patterns with `*` for skill name and `**` for nested directories.
+
+---
+
+## File Structure
+
+Every rule file follows this structure:
+
+1. **YAML frontmatter** — `paths:` field
+2. **Header** — `# [Folder Type] Rules`
+3. **Intro** — What this rule governs and why
+4. **File Structure** — What every file of this type must contain
+5. **Conventions** — Naming, formatting, and style rules
+6. **Examples** — Good vs bad illustrations
+7. **Cross-References** — Links to the syntax spec for full detail
+
+---
+
+## Rule Content Structure
+
+### Intro
+
+```markdown
+# Task Rules
+
+Rules for editing files in `tasks/`. Every task file must conform to these rules to ensure consistency across all skills.
+```
+
+### File Structure Section
+
+Define what every file of this type must contain:
+
+```markdown
+## File Structure
+
+Every task file must have these XML sections in order:
+
+1. `<purpose>` — What this task accomplishes (required)
+2. `<user-story>` — Who benefits and how (required)
+3. `<when-to-use>` — Trigger conditions (required)
+4. `<context>` — Files to read before starting (optional)
+5. `<references>` — Frameworks to lazy-load (optional)
+6. `<steps>` — Execution steps (required)
+7. `<output>` — What this task produces (required)
+8. `<acceptance-criteria>` — Completion verification (required)
+```
+
+### Conventions Section
+
+Define naming, formatting, and style rules:
+
+```markdown
+## Conventions
+
+### Naming
+- File name: kebab-case (`design-offer.md`, not `DesignOffer.md`)
+- Step names: snake_case attribute (`name="gather_requirements"`)
+
+### Formatting
+- No YAML frontmatter
+- Imperative voice in steps ("Ask the user" not "The user is asked")
+- Explicit wait points ("Wait for response before proceeding")
+
+### Acceptance Criteria
+- Plain checklists only (`- [ ]` format)
+- NOT BDD Given/When/Then
+- Each item must have clear pass/fail criterion
+```
+
+### Cross-References Section
+
+Point to the full syntax spec for comprehensive detail:
+
+```markdown
+## Full Specification
+
+See: `specs/tasks.md` for complete syntax specification including:
+- All XML section specifications with examples
+- Step element attributes and content rules
+- Conditional logic patterns
+- Good vs bad examples
+- Anti-patterns
+```
+
+---
+
+## Scope: Meta-Skill Only
+
+Rules live **exclusively** in the Forge meta-skill:
+
+```
+skills/
+  forge/                  # Meta-skill
+    forge.md              # Entry point
+    rules/                     # ← Rules live HERE
+      entry-point-rules.md
+      tasks-rules.md
+      templates-rules.md
+      frameworks-rules.md
+      context-rules.md
+      checklists-rules.md
+    tasks/
+    ...
+
+  revops-expert/               # Regular skill
+    revops-expert.md
+    tasks/                     # ← No rules/ folder
+    frameworks/
+    ...
+```
+
+**Why meta-skill only:** Individual skills follow the standards — they don't carry the rulebook. Rules are the meta-layer that Forge uses to validate and scaffold.
+
+---
+
+## How Rules Reference Specs
+
+Rules are the **enforcement layer**. Specs are the **source of truth**. Rules summarize what specs define in detail:
+
+```markdown
+## Relationship
+
+| Artifact | Purpose | Detail Level |
+|----------|---------|-------------|
+| **Spec** (`specs/tasks.md`) | Full syntax definition with rationale, examples, anti-patterns | Comprehensive |
+| **Rule** (`rules/tasks-rules.md`) | Quick-reference enforcement checklist | Summary |
+
+Rules say "what must be true." Specs explain "why and how."
+```
+
+A rule file should be concise enough to scan quickly during scaffolding. For the full explanation, it points to the spec.
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Rule file | `{folder-type}-rules.md` | `tasks-rules.md`, `entry-point-rules.md` |
+| Directory | Always `rules/` | `skills/forge/rules/` |
+| Paths glob | `skills/*/{folder}/**/*.md` | `skills/*/tasks/**/*.md` |
+
+---
+
+## Core Principle
+
+**Rules are the enforcement layer for specs.** They tell Forge what to check when scaffolding or auditing a skill. They are concise summaries, not comprehensive documentation.
+
+If someone asks "what must a task file contain?" — the rule answers in 30 seconds. If they ask "why, and what are the edge cases?" — the spec answers in 5 minutes.
+
+---
+
+## Good vs Bad Examples
+
+### Good: Concise Rule with Cross-Reference
+
+```yaml
+---
+paths:
+  - "skills/*/tasks/**/*.md"
+---
+```
+
+```markdown
+# Task Rules
+
+Rules for files in `tasks/`. Full specification: `specs/tasks.md`
+
+## Required Sections
+
+Every task file must have these XML sections:
+
+| Section | Required | Key Rule |
+|---------|----------|----------|
+| `<purpose>` | Yes | 1-2 sentences, specific |
+| `<user-story>` | Yes | "As a [role], I want [action], so that [outcome]" |
+| `<when-to-use>` | Yes | Bullet list of trigger conditions |
+| `<context>` | No | @-references only if genuinely needed |
+| `<references>` | No | Lazy-load with conditional notes |
+| `<steps>` | Yes | Named steps (`name="snake_case"`), imperative voice |
+| `<output>` | Yes | Artifact format and file location |
+| `<acceptance-criteria>` | Yes | Plain checklists, not BDD |
+
+## Quick Checks
+
+- [ ] No YAML frontmatter
+- [ ] All steps have `name` attribute (snake_case)
+- [ ] Acceptance criteria use `- [ ]` format (not Given/When/Then)
+- [ ] Output section specifies file location
+- [ ] Wait points are explicit ("Wait for response")
+
+## Full Specification
+
+See: `specs/tasks.md`
+```
+
+### Bad: Rule That Duplicates the Spec
+
+```markdown
+# Task Rules
+
+## Purpose Section
+The purpose section describes what the task accomplishes. It should be 1-2 sentences.
+Here's what a good purpose looks like...
+[300 lines of the spec repeated verbatim]
+```
+
+**Why bad:** Duplicates the spec — now changes must happen in two places. Rules summarize; specs detail.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Rules in individual skills | Every skill carries its own rulebook — maintenance nightmare | Rules in meta-skill only |
+| Rule duplicates full spec | Two sources of truth — drift inevitable | Rule summarizes, cross-references spec |
+| Missing `paths:` frontmatter | Tooling can't know which files the rule applies to | Always include paths glob |
+| Rule without quick checks | Can't scan quickly during scaffolding | Include checkbox summary |
+| Rules that prescribe content | Rules define structure, not domain content | Structure rules only — content comes from frameworks |