@accelerationguy/accel 1.0.0

package/modules/forge/specs/context.md

@@ -0,0 +1,223 @@
+# Context Syntax Spec
+
+Defines the syntax for context files: `context/*.md` — business and user state that personalizes skill behavior.
+
+**Applies to:** `skills/{skill-name}/context/*.md`
+
+---
+
+## No Frontmatter
+
+Context files do not use YAML frontmatter. They are plain markdown with standard sections. Content starts with a header.
+
+---
+
+## Context Subtypes
+
+### User Profile
+
+Personal information about the skill's user — preferences, history, identity.
+
+**Standard sections:**
+
+```markdown
+# User Profile
+
+## Identity
+- Name: [Full name]
+- Role: [Primary role or title]
+- Company: [Business name]
+
+## Preferences
+- Communication style: [Direct / Conversational / Formal]
+- Output format: [Markdown / PDF / Plain text]
+- Tone: [Professional / Casual / Technical]
+
+## History
+- Previous outputs: [Links or references to prior work]
+- Known constraints: [Time zones, tools, limitations]
+
+## Notes
+[Free-form notes that affect skill behavior]
+```
+
+### Business Profile
+
+Information about the business the skill serves — brand, positioning, audience.
+
+**Standard sections:**
+
+```markdown
+# Business Profile
+
+## Company
+- Name: [Business name]
+- Website: [URL]
+- Industry: [Primary industry]
+- Stage: [Startup / Growth / Established]
+
+## Brand Voice
+- Tone: [How the brand speaks]
+- Values: [Core principles]
+- Avoid: [Words, phrases, or approaches to never use]
+
+## Target Audience
+- Primary: [Who they serve]
+- Pain points: [What problems they solve]
+- Language: [How the audience talks about their problems]
+
+## Products/Services
+- [Product 1]: [Brief description and price point]
+- [Product 2]: [Brief description and price point]
+
+## Competitors
+- [Competitor 1]: [Key differentiator]
+- [Competitor 2]: [Key differentiator]
+```
+
+### Custom Context
+
+For domain-specific state that doesn't fit user or business profiles.
+
+**Naming:** Descriptive kebab-case — `pipeline-status.md`, `client-roster.md`, `campaign-history.md`
+
+**Structure:** Use headers that make sense for the domain. No rigid template — but maintain consistent formatting with other context files in the skill.
+
+---
+
+## Onboarding Template Pattern
+
+When context is missing, skills should gather it. Include an onboarding template that defines questions to ask:
+
+```markdown
+# Onboarding: User Profile
+
+## Questions
+
+Ask these questions when `context/user-profile.md` doesn't exist or is incomplete:
+
+1. What's your name and role?
+2. What's your business called and what do you do?
+3. How do you prefer output — formal or conversational?
+4. Any tools, platforms, or constraints I should know about?
+
+## After Gathering
+
+Create `context/user-profile.md` from responses using the standard user profile structure.
+```
+
+**Rules:**
+- Onboarding templates live alongside context files: `context/onboarding-user.md`
+- Tasks check for context existence before starting and route to onboarding if missing
+- Onboarding runs once — after gathering, context file exists for future sessions
+
+---
+
+## Loading Pattern
+
+Context files load on skill activation — they are "always load" in the entry point routing:
+
+```xml
+<!-- In entry point -->
+<routing>
+## Always Load
+@context/user-profile.md
+@context/business-profile.md
+
+## Load on Demand
+@frameworks/... (loaded by tasks when needed)
+</routing>
+```
+
+**Why always-load:** Context personalizes every interaction. Unlike frameworks (which are domain knowledge), context is identity — the skill needs it from the start.
+
+---
+
+## Distinction: Context vs Frameworks
+
+| Dimension | Context | Frameworks |
+|-----------|---------|------------|
+| **Contains** | State about this user/business | Knowledge about a domain |
+| **Mutability** | Mutable — updates as context changes | Read-only — never modified |
+| **Loading** | Always-load on activation | Lazy-load by tasks on demand |
+| **Example** | "Chris runs C&C Strategic Consulting" | "The Value Equation has four variables" |
+| **Lifespan** | Changes over time | Stable reference material |
+
+**Rule of thumb:** If it would be different for a different user → context. If it's the same regardless of user → framework.
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Context file | kebab-case, descriptive | `user-profile.md`, `business-profile.md` |
+| Onboarding file | `onboarding-{type}.md` | `onboarding-user.md` |
+| Directory | Always `context/` | `skills/revops-expert/context/` |
+
+---
+
+## Core Principle
+
+**Context is the skill's memory of who it's serving.** Without context, every interaction starts from zero. With context, the skill personalizes from the first word.
+
+Context files are the only mutable files in a skill directory. Everything else (entry point, tasks, frameworks, templates, checklists) is stable reference material.
+
+---
+
+## Good vs Bad Examples
+
+### Good: Structured Business Profile
+
+```markdown
+# Business Profile
+
+## Company
+- Name: C&C Strategic Consulting
+- Website: https://ccstrategic.io
+- Industry: AI implementation for agencies
+- Stage: Growth
+
+## Brand Voice
+- Tone: Direct, confident, no-fluff
+- Values: Results over promises, implementation over theory
+- Avoid: "Leverage", "synergy", buzzword-heavy language
+
+## Target Audience
+- Primary: Agency owners doing $500K-$5M/year
+- Pain points: Manual processes eating margins, can't scale without hiring
+- Language: "I need more time", "I'm doing everything myself", "My team can't keep up"
+
+## Products/Services
+- AI Agent Setup: Done-for-you automation — $4,997
+- Voice AI Employee: Handles calls 24/7 — $2,497/mo
+- CRM Automation: GoHighLevel setup — $1,997
+
+## Competitors
+- Generic AI agencies: Lower price, no specialization
+- In-house hires: Higher cost, slower ramp
+```
+
+### Bad: Vague Context
+
+```markdown
+# Business
+
+We do AI stuff for agencies. Our clients are business owners.
+We charge various prices depending on the project.
+```
+
+**Why bad:** No structure, no specifics the skill can use. "AI stuff" and "various prices" give the skill nothing to personalize with.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Domain knowledge in context files | Mixes state with reference — hard to maintain | Move knowledge to `frameworks/`, keep context for state |
+| No onboarding path | Skill fails silently when context is missing | Add onboarding template with questions |
+| Loading context on demand | Skill gives generic responses until context loads | Always-load context at activation |
+| Stale context never updated | Skill uses outdated information | Note update triggers in each section |
+| Context file too large | Wastes context window on low-value details | Keep profiles concise — move history to separate files |
+| Hardcoded context in entry point | Can't be updated without editing skill source | Always use separate context files |

package/modules/forge/specs/entry-point.md

@@ -0,0 +1,320 @@
+# Entry Point Syntax Spec
+
+Defines the syntax for skill entry points: `{skill-name}.md` — the file that loads when a user invokes a skill via slash command.
+
+**Applies to:** `skills/{skill-name}/{skill-name}.md`
+
+---
+
+## YAML Frontmatter
+
+Every entry point starts with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+type: standalone
+version: 0.1.0
+category: operations
+description: One-line description of what this skill does
+allowed-tools: [Read, Write, Glob, Grep, Edit, AskUserQuestion]
+---
+```
+
+### Frontmatter Fields
+
+| Field | Required | Type | Purpose | Example |
+|-------|----------|------|---------|---------|
+| `name` | Yes | string | Skill identifier (kebab-case, matches directory) | `revops-expert` |
+| `type` | Yes | enum | Skill tier | `suite`, `standalone`, `task-only` |
+| `version` | Yes | semver | Current version | `0.1.0` |
+| `category` | Yes | string | Domain grouping | `operations`, `content`, `development` |
+| `description` | Yes | string | One-line summary | `Revenue operations expert for offer design and webinar builds` |
+| `allowed-tools` | No | array | Tools this skill may use | `[Read, Write, Bash, AskUserQuestion]` |
+
+### Skill Types
+
+| Type | Description | Structure |
+|------|------------|-----------|
+| `suite` | Meta-orchestrator with sub-skills | Entry point + multiple `{sub-skill}.md` files at root |
+| `standalone` | Single skill with auxiliary folders | Entry point + `tasks/`, `frameworks/`, etc. |
+| `task-only` | Lightweight single-purpose guide | Entry point only, no auxiliary folders. Invoked by parent skill. |
+
+### Versioning Convention
+
+Use semantic versioning: `MAJOR.MINOR.PATCH`
+
+| Bump | When | Example |
+|------|------|---------|
+| PATCH | Fix typos, clarify instructions, minor wording | `0.1.0` → `0.1.1` |
+| MINOR | Add new task, new framework, expand capability | `0.1.0` → `0.2.0` |
+| MAJOR | Restructure skill, change persona, breaking changes | `0.2.0` → `1.0.0` |
+
+Start at `0.1.0` for new skills. Bump to `1.0.0` after validation in production use.
+
+---
+
+## XML Sections
+
+Entry points use semantic XML sections in this order:
+
+### Section Order
+
+1. `<activation>` — When and how this skill triggers (always present)
+2. `<persona>` — Voice, tone, expertise (always present)
+3. `<commands>` — Available sub-commands (if applicable)
+4. `<routing>` — What to load: tasks, frameworks, context (always present)
+5. `<greeting>` — Initial response when skill loads (always present)
+
+### Section Specifications
+
+#### `<activation>`
+
+Defines when and how the skill is invoked. Replaces Drive's `<objective>`.
+
+**Contains:**
+- What the skill does (1-2 sentences)
+- When to use it (trigger conditions)
+- What it does NOT do (scope boundaries)
+
+```xml
+<activation>
+## What
+Revenue operations expert for designing offers, building webinar funnels, and writing conversion copy.
+
+## When to Use
+- Designing a new offer or pricing structure
+- Building webinar content and funnels
+- Writing sales copy using proven frameworks
+
+## Not For
+- Technical implementation (use /frontend-design)
+- Content scheduling (use /content-manager)
+</activation>
+```
+
+#### `<persona>`
+
+Defines the skill's voice and expertise. Skills have personas; raw commands don't.
+
+**Contains:**
+- Role definition (who this skill acts as)
+- Communication style (how it speaks)
+- Expertise areas (what it knows deeply)
+
+```xml
+<persona>
+## Role
+Senior revenue operations strategist with 15 years building 8-figure funnels.
+
+## Style
+- Direct and opinionated — recommends one path, not five options
+- Uses frameworks by name (Perfect Webinar, Value Equation)
+- Challenges weak offers before building on them
+
+## Expertise
+- Offer design (Hormozi Value Equation)
+- Webinar structure (Brunson Perfect Webinar)
+- Sales copy (PAS, AIDA, Story-Offer-Close)
+</persona>
+```
+
+#### `<commands>`
+
+Lists available sub-commands. Omit for `task-only` skills.
+
+**Contains:**
+- Command name, description, and routing target
+
+```xml
+<commands>
+| Command | Description | Routes To |
+|---------|-------------|-----------|
+| `/skill-name build` | Full guided build | tasks/full-build.md |
+| `/skill-name review` | Review existing work | tasks/review.md |
+| `/skill-name frameworks` | Browse loaded frameworks | frameworks/ |
+</commands>
+```
+
+For suites, list sub-skill entry points instead:
+
+```xml
+<commands>
+| Sub-Skill | Description | Entry Point |
+|-----------|-------------|-------------|
+| `/suite offer` | Design offers | offer.md |
+| `/suite webinar` | Build webinars | webinar.md |
+| `/suite copy` | Write sales copy | copy.md |
+</commands>
+```
+
+#### `<routing>`
+
+Defines what auxiliary files to load and when. Replaces Drive's `<execution_context>`.
+
+**Contains:**
+- @-references to tasks, frameworks, context files
+- Loading conditions (always vs on-demand)
+
+```xml
+<routing>
+## Always Load
+@context/user-profile.md
+@context/business-profile.md
+
+## Load on Command
+@tasks/full-build.md (when user runs /skill-name build)
+@tasks/review.md (when user runs /skill-name review)
+
+## Load on Demand
+@frameworks/hormozi-value-equation.md (when designing offers)
+@frameworks/brunson-perfect-webinar.md (when building webinars)
+</routing>
+```
+
+#### `<greeting>`
+
+Initial response when the skill loads. Sets expectations and offers entry points.
+
+**Contains:**
+- Brief intro (1-2 sentences)
+- Available actions
+- Prompt for user intent
+
+```xml
+<greeting>
+RevOps Expert loaded.
+
+Available actions:
+- **Build** — Full guided build (offer, webinar, or copy)
+- **Review** — Audit existing work against frameworks
+
+What are you working on?
+</greeting>
+```
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Skill directory | kebab-case | `revops-expert/` |
+| Entry point file | Matches directory name | `revops-expert.md` |
+| Sub-skill files (suite) | kebab-case at root | `offer-design.md` |
+| Slash command | Matches directory | `/revops-expert` |
+
+---
+
+## Core Principle
+
+**Entry points are thin.** They define identity and route to heavy work.
+
+An entry point should fit on one screen. If it grows beyond that, logic belongs in `tasks/`.
+
+Entry points answer "what am I and where do things live." Tasks answer "how to do the work."
+
+---
+
+## Good vs Bad Examples
+
+### Good: Thin Entry Point
+
+```yaml
+---
+name: content-manager
+type: standalone
+version: 0.2.0
+category: content
+description: Manage shortform content pipeline from script to publish
+---
+```
+
+```xml
+<activation>
+## What
+Manages the shortform content pipeline: triage scripts, track status, move content through stages.
+
+## When to Use
+- Reviewing what scripts are ready
+- Moving content through recording → editing → scheduling → published
+- Generating new script drafts
+</activation>
+
+<persona>
+## Role
+Content pipeline manager — organized, status-focused, action-oriented.
+
+## Style
+- Shows pipeline status as tables
+- Suggests next actions based on what's stale
+- Keeps responses tight — no lengthy explanations
+</persona>
+
+<routing>
+## Always Load
+@context/pipeline-status.md
+
+## Load on Command
+@tasks/generate-script.md (when creating new scripts)
+@tasks/update-status.md (when moving content through stages)
+</routing>
+
+<greeting>
+Content Manager loaded. Checking pipeline status...
+
+What do you need?
+- **Status** — See what's in each stage
+- **Generate** — Write a new script
+- **Update** — Move content to next stage
+</greeting>
+```
+
+### Bad: Entry Point Doing Heavy Work
+
+```yaml
+---
+name: content-manager
+type: standalone
+version: 1.0.0
+category: content
+description: Content pipeline manager
+---
+```
+
+```xml
+<!-- BAD: Process logic belongs in tasks/, not the entry point -->
+<activation>
+Manages content pipeline.
+</activation>
+
+<process>
+1. Read all files in content/shortform/scripts/
+2. Parse YAML frontmatter from each file
+3. Group by status: triage, ready, recorded, editing, scheduled, published
+4. Display as table
+5. Ask user what to do next
+6. If generating script:
+   a. Ask for topic
+   b. Ask for platform
+   c. Generate using hook framework
+   d. Write to file
+   ...50 more lines...
+</process>
+```
+
+**Why bad:** The entry point became a workflow. Extract step 1-5 into `tasks/check-status.md` and step 6 into `tasks/generate-script.md`.
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| Process logic in entry point | Entry point becomes unmaintainable, can't reuse tasks | Move to `tasks/` |
+| Generic XML tags (`<section>`, `<block>`) | Loses semantic meaning, harder to parse | Use semantic tags: `<activation>`, `<persona>`, `<routing>` |
+| Missing `<activation>` scope boundaries | Skill tries to do everything, confuses users | Add "Not For" section |
+| Version stuck at `1.0.0` | No evolution tracking, can't rollback | Start at `0.1.0`, bump meaningfully |
+| Vague `<persona>` | Skill has no voice, responses feel generic | Define role, style, and expertise concretely |
+| Loading everything in `<routing>` | Wastes context window on irrelevant content | Use "Load on Demand" for conditional files |
+| No `<greeting>` | User gets no orientation, doesn't know what's available | Always include greeting with available actions |