@accelerationguy/accel 1.0.0

package/modules/forge/specs/tasks.md

@@ -0,0 +1,344 @@
+# Tasks Syntax Spec
+
+Defines the syntax for task files: `tasks/*.md` — step-by-step guided workflows that do the heavy work.
+
+**Applies to:** `skills/{skill-name}/tasks/*.md`
+
+---
+
+## No Frontmatter
+
+Tasks do not use YAML frontmatter. Content starts immediately with semantic XML. This matches Drive workflow convention — tasks are execution files, not metadata-bearing artifacts.
+
+---
+
+## XML Sections
+
+Tasks use semantic XML sections in this order:
+
+### Section Order
+
+1. `<purpose>` — What this task accomplishes (always present)
+2. `<user-story>` — Who benefits and how (always present)
+3. `<when-to-use>` — Trigger conditions (always present)
+4. `<context>` — Files to read before starting (if needed)
+5. `<references>` — Frameworks to lazy-load (if needed)
+6. `<steps>` — Execution steps (always present)
+7. `<output>` — What this task produces (always present)
+8. `<acceptance-criteria>` — How to verify completion (always present)
+
+### Section Specifications
+
+#### `<purpose>`
+
+One to two sentences describing what this task accomplishes.
+
+```xml
+<purpose>
+Guide the user through designing a complete offer using the Hormozi Value Equation. Produces a structured offer document ready for sales copy.
+</purpose>
+```
+
+#### `<user-story>`
+
+Defines who this task serves and the outcome they get.
+
+**Format:** As a [role], I want [action], so that [outcome].
+
+```xml
+<user-story>
+As a business owner, I want to design a structured offer using proven frameworks, so that my offer is compelling and I don't leave money on the table.
+</user-story>
+```
+
+#### `<when-to-use>`
+
+Decision criteria for invoking this task. Helps the entry point route correctly.
+
+```xml
+<when-to-use>
+- User explicitly asks to design or redesign an offer
+- User has a product/service but no structured pricing
+- Entry point routes here via `/revops-expert build offer`
+</when-to-use>
+```
+
+#### `<context>`
+
+Files to read before starting execution. Equivalent to Drive's `<required_reading>`.
+
+```xml
+<context>
+@context/user-profile.md
+@context/business-profile.md
+</context>
+```
+
+Only include files genuinely needed. Do not reflexively load everything.
+
+#### `<references>`
+
+Frameworks to lazy-load when relevant during execution. Not pre-loaded — read when a step needs them.
+
+```xml
+<references>
+@frameworks/hormozi-value-equation.md (during pricing step)
+@frameworks/risk-reversal-patterns.md (during guarantee step)
+</references>
+```
+
+#### `<steps>`
+
+The execution logic. This is where the heavy work lives.
+
+**Step elements:**
+
+```xml
+<step name="snake_case_name" priority="first">
+Imperative instructions here.
+
+1. Do this first
+2. Then do this
+3. Finally do this
+</step>
+```
+
+**Step attributes:**
+
+| Attribute | Required | Purpose | Values |
+|-----------|----------|---------|--------|
+| `name` | Yes | Identifier (snake_case) | `gather_requirements`, `design_pricing` |
+| `priority` | No | Ordering hint | `first`, `last` |
+
+**Step content rules:**
+- Imperative voice: "Ask the user" not "The user is asked"
+- Numbered sub-steps for sequential actions
+- Prose for conditional logic or decision trees
+- Can include `<if>` elements for conditional behavior
+
+**Conditional logic within steps:**
+
+```xml
+<step name="determine_approach">
+<if condition="user has existing offer">
+  Review current offer structure.
+  Identify gaps using Value Equation.
+  Recommend specific improvements.
+</if>
+
+<if condition="user starting from scratch">
+  Start with dream outcome identification.
+  Walk through full Value Equation build.
+</if>
+</step>
+```
+
+**Wait points within steps:**
+
+When a step requires user input before continuing, use explicit wait signals:
+
+```xml
+<step name="gather_requirements">
+Ask the user:
+1. What is your product or service?
+2. Who is your ideal customer?
+3. What is their dream outcome?
+
+**Wait for response before proceeding.**
+
+Once received, summarize back to confirm understanding.
+</step>
+```
+
+#### `<output>`
+
+Defines what this task produces. Be specific about format and location.
+
+```xml
+<output>
+## Artifact
+Structured offer document in markdown.
+
+## Format
+```markdown
+# [Offer Name]
+
+## Dream Outcome
+[What the customer gets]
+
+## Perceived Likelihood
+[Why they'll believe it works]
+
+## Time Delay
+[How fast they get results]
+
+## Effort & Sacrifice
+[What they don't have to do]
+
+## Price
+[Pricing structure]
+
+## Guarantee
+[Risk reversal]
+```
+
+## Location
+Write to: `output/{offer-name}-offer.md`
+</output>
+```
+
+#### `<acceptance-criteria>`
+
+How to verify the task completed successfully. Uses **plain checklists** (not BDD Given/When/Then).
+
+```xml
+<acceptance-criteria>
+- [ ] Offer document created with all Value Equation sections
+- [ ] Dream outcome is specific and measurable
+- [ ] Price anchored against value (not cost)
+- [ ] Guarantee includes specific risk reversal mechanism
+- [ ] User confirmed the offer matches their intent
+</acceptance-criteria>
+```
+
+**Checklist rules:**
+- Each item has a clear pass/fail criterion
+- Items are independently verifiable
+- Include both output checks and quality checks
+- Always include user confirmation as final item
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Task file | kebab-case | `full-build.md`, `design-offer.md` |
+| Step names | snake_case | `name="gather_requirements"` |
+| Directory | Always `tasks/` | `skills/revops-expert/tasks/` |
+
+---
+
+## Core Principle
+
+**Tasks contain the heavy logic.** Entry points route here; tasks execute.
+
+A task can be long and detailed. It answers "how to do it" comprehensively. If a task grows beyond a single concern, split into multiple tasks — not into a longer task.
+
+---
+
+## Good vs Bad Examples
+
+### Good: Structured Task with Clear Steps
+
+```xml
+<purpose>
+Generate a shortform video script for LinkedIn or Instagram based on a topic and hook.
+</purpose>
+
+<user-story>
+As a content creator, I want a structured script for a 60-second video, so that I can record without improvising and stay on message.
+</user-story>
+
+<when-to-use>
+- User has a topic and wants a script
+- Entry point routes here via /content-manager generate
+</when-to-use>
+
+<references>
+@frameworks/hook-patterns.md (during hook selection)
+</references>
+
+<steps>
+
+<step name="gather_input" priority="first">
+Ask the user:
+1. What topic or lesson do you want to share?
+2. Target platform: LinkedIn or Instagram?
+3. Any specific angle or hook in mind?
+
+**Wait for response.**
+</step>
+
+<step name="select_hook">
+Load @frameworks/hook-patterns.md
+
+Based on the topic, select 2-3 hook options:
+- Pattern interrupt hook
+- Contrarian hook
+- Story hook
+
+Present options. Let user choose or request alternatives.
+
+**Wait for selection.**
+</step>
+
+<step name="write_script">
+Write the script following this structure:
+1. Hook (selected above) — first 3 seconds
+2. Context — why this matters (10 seconds)
+3. Core lesson — the insight (30 seconds)
+4. CTA — what to do next (5 seconds)
+
+Keep total under 150 words for 60-second delivery.
+</step>
+
+<step name="review_and_refine">
+Present the script to the user.
+Ask: "Does this capture your message? Any adjustments?"
+
+**Wait for approval or revision requests.**
+
+If revisions requested, adjust and re-present.
+</step>
+
+</steps>
+
+<output>
+## Artifact
+Script in markdown with sections labeled.
+
+## Location
+Write to: content/shortform/scripts/0-triage/{platform}-{topic-slug}.md
+</output>
+
+<acceptance-criteria>
+- [ ] Script has hook, context, core lesson, and CTA sections
+- [ ] Total word count under 150 words
+- [ ] Platform-appropriate formatting (LinkedIn vs Instagram)
+- [ ] User approved final script
+</acceptance-criteria>
+```
+
+### Bad: Vague Task with No Structure
+
+```xml
+<!-- BAD: No user story, no step names, no acceptance criteria -->
+<purpose>
+Generate a script.
+</purpose>
+
+<steps>
+Ask the user what they want to talk about.
+Then write a script.
+Make it good.
+Show it to them.
+</steps>
+```
+
+**Why bad:** No user story (who is this for?), no step names (can't reference or skip steps), instructions are vague ("make it good"), no output spec, no acceptance criteria.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| No `<user-story>` | Task has no clear beneficiary or outcome | Always define who benefits and what they get |
+| Unnamed steps | Can't reference, skip, or debug specific steps | Always use `<step name="snake_case">` |
+| "Make it good" instructions | Vague — Claude will interpret differently each time | Be specific: "Keep under 150 words", "Include 3 options" |
+| No wait points | Task races through without user input | Add explicit "Wait for response" signals |
+| BDD acceptance criteria | Over-formal for skill context, adds friction | Use plain checklists: `- [ ] Specific criterion` |
+| Monolithic task | Single task trying to do everything | Split into focused tasks, each with one concern |
+| Loading all frameworks upfront | Wastes context on irrelevant knowledge | Use `<references>` with conditional loading notes |
+| Missing `<output>` section | No one knows what the task produces or where | Always specify artifact format and location |

package/modules/forge/specs/templates.md

@@ -0,0 +1,335 @@
+# Templates Syntax Spec
+
+Defines the syntax for template files: `templates/*.md` — fill-in-the-blank structures that define output formats.
+
+**Applies to:** `skills/{skill-name}/templates/*.md`
+
+---
+
+## File Structure
+
+Every template follows this structure in order:
+
+1. **Header** — `# [Name] Template`
+2. **Intro** — Brief description and output file naming pattern
+3. **File Template block** — The actual template in a fenced code block
+4. **Field Documentation** — Tables explaining variable fields
+5. **Section Specifications** — Detailed guidance for each section in the template
+
+---
+
+## Header and Intro
+
+```markdown
+# Offer Design Template
+
+Template for `output/{offer-name}-offer.md` — structured offer documents using the Value Equation.
+
+**Purpose:** Produce consistent offer documents that capture all Value Equation components.
+
+---
+```
+
+The intro includes:
+- What output this template produces
+- File naming pattern with variables in `{curly braces}`
+- One-line purpose statement
+
+---
+
+## File Template Block
+
+The actual template lives in a fenced markdown code block. This is what gets copied and populated during skill execution.
+
+````markdown
+## File Template
+
+```markdown
+# {offer-name}
+
+## Dream Outcome
+[Describe the specific, measurable result the customer achieves]
+
+## Perceived Likelihood of Achievement
+[Why the customer will believe this works — proof, credentials, method]
+
+## Time Delay
+[How quickly they see results — be specific: days, weeks, not "fast"]
+
+## Effort & Sacrifice
+[What they DON'T have to do — remove friction, pain, and effort]
+
+## Price
+**Anchor:** [Value of the outcome in dollars]
+**Price:** [Actual price]
+**Ratio:** [X:1 value-to-price ratio]
+
+## Guarantee
+[Specific risk reversal — what happens if it doesn't work]
+
+## Bonuses
+- [Bonus 1]: [What it is] — Value: [dollar amount]
+- [Bonus 2]: [What it is] — Value: [dollar amount]
+
+## Stack Summary
+| Component | Value |
+|-----------|-------|
+| [Core offer] | [value] |
+| [Bonus 1] | [value] |
+| [Bonus 2] | [value] |
+| **Total Value** | **[total]** |
+| **Price** | **[price]** |
+
+---
+*Generated by /revops-expert on [date]*
+```
+````
+
+---
+
+## Placeholder Conventions
+
+Two placeholder types. Use consistently across ALL templates in ALL skills.
+
+### Square Brackets: `[Human-Fillable Prose]`
+
+For content that requires human judgment, creativity, or context-specific writing.
+
+```markdown
+[Describe the specific, measurable result the customer achieves]
+[Why the customer will believe this works]
+[What they DON'T have to do]
+```
+
+**Rules:**
+- Always include guidance text inside the brackets
+- Guidance should be specific enough to fill without asking questions
+- Use imperative voice: "Describe..." not "A description of..."
+
+### Curly Braces: `{variable-interpolation}`
+
+For programmatic values that get substituted automatically during generation.
+
+```markdown
+{offer-name}
+{date}
+{client-name}
+{skill-name}
+```
+
+**Rules:**
+- kebab-case for multi-word variables
+- Variables are resolved at generation time, not by the user
+- Use for: names, dates, paths, IDs, computed values
+
+### Comparison
+
+| Placeholder | Syntax | Filled By | Example |
+|-------------|--------|-----------|---------|
+| Human prose | `[guidance text]` | Skill author or user during execution | `[Describe the dream outcome]` |
+| Variable | `{variable-name}` | Scaffolding engine or skill runtime | `{offer-name}`, `{date}` |
+
+---
+
+## Content Frontmatter vs Template Frontmatter
+
+Templates may contain YAML frontmatter **inside** the fenced code block. This is content TO BE GENERATED, not metadata about the template file itself.
+
+**Template files themselves do NOT have frontmatter.** The frontmatter appears inside the template content:
+
+````markdown
+## File Template
+
+```markdown
+---
+name: {skill-name}
+type: standalone
+version: 0.1.0
+category: [Primary domain this skill serves]
+description: [One-line description]
+---
+
+<activation>
+[Activation content]
+</activation>
+```
+````
+
+**Key distinction:**
+- The `---` block inside the fenced code is **generated content** — it will appear in the output file
+- The template file itself starts with `# [Name] Template` — no frontmatter
+
+---
+
+## Field Documentation
+
+After the fenced template block, include a table documenting each variable field:
+
+```markdown
+## Field Documentation
+
+| Field | Type | Required | Purpose | Example |
+|-------|------|----------|---------|---------|
+| `{offer-name}` | variable | Yes | URL-safe offer identifier | `ai-automation-agency` |
+| `[Dream Outcome]` | prose | Yes | Specific measurable result | `Generate 20 qualified leads per month` |
+| `[Perceived Likelihood]` | prose | Yes | Proof and credibility | `Case study: Client X achieved Y in Z weeks` |
+| `[Price]` | prose | Yes | Pricing with anchor | `Anchor: $50,000 value / Price: $4,997` |
+```
+
+**Table rules:**
+- List every placeholder (both `[prose]` and `{variable}`)
+- Mark required vs optional
+- Include concrete examples
+- Group by section if the template is large
+
+---
+
+## Section Specifications
+
+For templates with multiple sections, explain what each section contains:
+
+```markdown
+## Section Specifications
+
+### Dream Outcome
+**Purpose:** The specific result the customer achieves.
+**Length:** 1-3 sentences.
+**Quality check:** Is it specific and measurable? "Grow your business" fails. "Generate 20 qualified leads per month" passes.
+
+### Perceived Likelihood
+**Purpose:** Why the customer believes this will work for them.
+**Contains:** Proof elements — case studies, credentials, methodology.
+**Quality check:** Would a skeptic find this credible?
+
+### Price
+**Purpose:** Pricing anchored against delivered value.
+**Contains:** Value anchor, actual price, value-to-price ratio.
+**Quality check:** Is the ratio at least 3:1? If not, revisit value stack.
+```
+
+**Spec rules:**
+- Purpose: what the section achieves
+- Length or contains: structural guidance
+- Quality check: pass/fail criterion for the content
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Template file | kebab-case | `offer-design.md`, `webinar-outline.md` |
+| Directory | Always `templates/` | `skills/revops-expert/templates/` |
+| Output file pattern | Use `{variables}` | `output/{offer-name}-offer.md` |
+
+---
+
+## Core Principle
+
+**Templates define structure, not content.** They answer "what shape should the output take?" — the skill's tasks fill in the actual content.
+
+Templates are reference documents. They are read during task execution to ensure consistent output format. They are never modified during execution.
+
+---
+
+## Good vs Bad Examples
+
+### Good: Complete Template with Documentation
+
+````markdown
+# Script Template
+
+Template for `content/shortform/scripts/0-triage/{platform}-{topic-slug}.md` — shortform video scripts.
+
+**Purpose:** Consistent script format across all shortform content.
+
+---
+
+## File Template
+
+```markdown
+---
+status: triage
+platform: {platform}
+topic: {topic}
+created: {date}
+---
+
+# {topic}
+
+## Hook (0-3 seconds)
+[Opening line that stops the scroll — pattern interrupt, contrarian, or story]
+
+## Context (3-13 seconds)
+[Why this matters to the viewer — bridge from hook to lesson]
+
+## Core Lesson (13-45 seconds)
+[The insight, framework, or actionable advice]
+
+## CTA (45-55 seconds)
+[What to do next — follow, comment, link in bio]
+
+---
+Word count target: 120-150 words
+```
+
+---
+
+## Field Documentation
+
+| Field | Type | Required | Purpose | Example |
+|-------|------|----------|---------|---------|
+| `{platform}` | variable | Yes | Target platform | `linkedin`, `instagram` |
+| `{topic-slug}` | variable | Yes | URL-safe topic | `ai-automation-myths` |
+| `{topic}` | variable | Yes | Display topic | `AI Automation Myths` |
+| `{date}` | variable | Yes | Creation date | `2026-03-04` |
+| `[Hook]` | prose | Yes | Scroll-stopping opener | `"Everyone says AI will replace you. They're wrong."` |
+| `[Core Lesson]` | prose | Yes | Main insight | Actionable framework or contrarian take |
+
+## Section Specifications
+
+### Hook
+**Purpose:** Stop the scroll in the first 3 seconds.
+**Length:** 1-2 sentences, under 15 words.
+**Quality check:** Would YOU stop scrolling for this? If not, rewrite.
+
+### Core Lesson
+**Purpose:** The one thing the viewer takes away.
+**Length:** 3-5 sentences.
+**Quality check:** Is there a specific, actionable takeaway? "AI is cool" fails. "Use this 3-step framework to automate client onboarding" passes.
+````
+
+### Bad: Template Without Documentation
+
+````markdown
+# Script Template
+
+```markdown
+# Script
+
+## Hook
+Write a hook here.
+
+## Body
+Write the main content.
+
+## CTA
+Write a call to action.
+```
+````
+
+**Why bad:** No file naming pattern, no field documentation, placeholder text gives no guidance ("Write a hook here" — what makes a good hook?), no section specs, no quality checks.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Template file has YAML frontmatter | Confuses template metadata with generated content | Templates start with `# [Name] Template` — frontmatter goes inside fenced block only |
+| Vague placeholders: `[Write something here]` | Gives no guidance on what to write | Be specific: `[Opening line that stops the scroll]` |
+| No field documentation | Users don't know what each field expects | Add table after fenced block |
+| No section specifications | Quality is inconsistent across outputs | Add purpose, length, quality check for each section |
+| Missing file naming pattern | Outputs land in random locations | Specify pattern in intro: `output/{name}-{type}.md` |
+| Mixing placeholder types | `[variable]` where `{variable}` should be, or vice versa | `[square]` = human prose, `{curly}` = auto-interpolated |
+| Template modified during execution | Breaks the reference for future use | Templates are read-only — write output to separate files |