Skill: ivangdavila/agency (version 1.0.1)

--- name: Agency slug: agency version: 1.0.1 description: Build and operate a service agency with client management, project tracking, pricing, and team coordination. metadata: {"clawdbot":{"emoji":"🏢","requires":{"bins":[]},"os":["linux","darwin","win32"]}} --- ## When to Use User wants to start or scale a service agency: marketing, development, design, consulting, content, automation, or any service business. Agent handles operations so human focuses on clients and strategy. ## Quick Reference | Area | File | |------|------| | Client onboarding | `onboarding.md` | | Pricing and proposals | `pricing.md` | | Project management | `projects.md` | | Client communication | `communication.md` | | Deliverables workflow | `deliverables.md` | | Team coordination | `team.md` | | Agency-type specifics | `by-type.md` | | Learning system | `feedback.md` | ## Workspace Structure Agency data lives in ~/agency/: ``` ~/agency/ ├── clients/ # One file per client │ ├── index.md # Client list with status │ └── [name].md # Client profile, history, preferences ├── projects/ # Active project tracking ├── templates/ # Reusable proposals, briefs, reports ├── knowledge/ # SOPs, learnings, case studies └── config.md # Rates, margins, team structure ``` ## Core Operations **Client intake:** Brief arrives (audio, email, doc) → Extract scope, budget, timeline → Generate structured brief → Flag red flags (scope creep, unrealistic deadlines) → Create client folder. **Pricing:** Given scope → Apply rate card from config → Calculate estimate with complexity multipliers → Generate proposal PDF → Compare with historical similar projects. **Project tracking:** Maintain unified board of all active projects → Alert on deadlines → Detect stalled projects → Generate weekly status by client. **Deliverables:** Transform rough notes/input → Structured deliverable → Review against brief → Adapt to multiple formats if needed. ## Critical Rules - Never send proposals or communicate with clients without human approval - Track time/cost vs estimates — alert when project is losing money - Learn from corrections — update templates and knowledge base - Maintain client context across sessions — refer to history ## Config Fields Create ~/agency/config.md with rates, team, and margins. See `pricing.md` for format.

path: by-type.md
content: # Agency Type Specifics

## Marketing Agency

**Key metrics to track:**
- Client MRR/revenue
- Campaign performance (ROAS, CPA, CTR)
- Content engagement
- Lead generation

**Typical deliverables:**
- Content calendars
- Social media posts
- Ad creatives and copy
- Performance reports
- Strategy documents

**Common scope creep:**
- "Can you just post this too?"
- Unlimited revision rounds on ads
- Channel expansion without budget increase

**Tools to integrate:**
- Meta Business Suite
- Google Ads/Analytics
- Social scheduling tools
- Email marketing platforms

---

## Development Agency

**Key metrics to track:**
- Sprint velocity
- Bug count and resolution time
- Deploy frequency
- Technical debt

**Typical deliverables:**
- Working software
- Technical documentation
- API specs
- Deployment guides

**Common scope creep:**
- "Just one more feature"
- Undefined "bug fixes" that are actually features
- Integration with systems not in original scope

**Tools to integrate:**
- GitHub/GitLab
- Project management (Linear, Jira)
- CI/CD systems
- Error monitoring

---

## Design Agency

**Key metrics to track:**
- Revision rounds used
- Time to first concept
- Client satisfaction
- Portfolio-worthy output

**Typical deliverables:**
- Brand identity
- UI/UX designs
- Marketing collateral
- Brand guidelines

**Common scope creep:**
- "Can you try a completely different direction?"
- Stakeholder additions mid-project
- Format additions (print added to digital scope)

**Tools to integrate:**
- Figma
- Asset management
- Feedback tools (Loom, Markup)

---

## Consulting Agency

**Key metrics to track:**
- Recommendations implemented
- Measurable client outcomes
- Repeat business rate
- Thought leadership output

**Typical deliverables:**
- Diagnostic reports
- Strategy documents
- Implementation roadmaps
- Executive presentations

**Common scope creep:**
- "Can you help us implement too?"
- Additional stakeholder interviews
- Expanded diagnostic scope

**Tools to integrate:**
- Knowledge base
- Data analysis tools
- Presentation tools

---

## Content Agency

**Key metrics to track:**
- Content volume produced
- SEO rankings achieved
- Engagement metrics
- Client retention

**Typical deliverables:**
- Blog posts and articles
- Social content
- Video scripts
- SEO reports

**Common scope creep:**
- Additional platforms
- Shorter review cycles
- "Can you also manage posting?"

**Tools to integrate:**
- SEO tools (Ahrefs, SEMrush)
- Content calendars
- Publishing platforms

---

## Automation Agency

**Key metrics to track:**
- Hours saved for client
- Automation reliability (uptime)
- ROI delivered
- Support tickets

**Typical deliverables:**
- Workflow implementations
- Integration setups
- Documentation
- Training materials

**Common scope creep:**
- "Can it also do X?"
- Legacy system integrations
- Ongoing support expectations

**Tools to integrate:**
- Automation platforms (Make, n8n, Zapier)
- API connections
- Monitoring systems


path: communication.md
content: # Client Communication

## Communication Principles

- Proactive > reactive — tell them before they ask
- Structured > stream of consciousness
- Written trail for important decisions
- Match their communication style (formal/casual)

## Weekly Status Template

```
Subject: [Project Name] - Week of [Date] Update

Hi [Name],

**Progress this week:**
- [Completed item 1]
- [Completed item 2]

**In progress:**
- [Item 1] — expected [date]

**Waiting on you:**
- [Item needing client input] — please by [date]

**Next week:**
- [Planned work]

[If issues:] **Heads up:** [issue and proposed solution]

Questions? Just reply.

[Signature]
```

## Handling Different Situations

### Client asks for status (ad-hoc)
- Check project board
- Summarize current phase, recent progress, next steps
- Flag any blockers or needs from them

### Client provides chaotic feedback
- Parse into structured list
- Categorize: bug fix / enhancement / scope change
- Respond with clarified list for confirmation

### Client requests scope change
- Acknowledge the request
- Assess impact (hours, timeline, cost)
- Propose options:
  - Add with additional budget
  - Swap for something of equal size
  - Defer to phase 2

### Client is slow to respond
- Day 3: gentle reminder
- Day 7: more urgent, explain impact on timeline
- Day 10: escalate to decision maker or pause

### Client is unhappy
- Acknowledge their frustration (don't defend)
- Clarify the specific issue
- Propose concrete resolution
- Draft response for human review before sending

## Response Templates

**Acknowledging feedback:**
> Thanks for the detailed feedback. To confirm I've captured everything correctly:
> 1. [item]
> 2. [item]
> Let me know if I missed anything before we proceed.

**Scope change response:**
> I can definitely look into [request]. Just to set expectations, this would be [additional scope/time/cost]. Want me to send a quick change order, or should we save it for phase 2?

**Deadline risk communication:**
> Wanted to give you a heads up: [issue] is putting our [date] deadline at risk. Here's what I recommend: [solution]. Let me know how you'd like to proceed.

**Invoice follow-up (gentle):**
> Just floating this to the top of your inbox — invoice [#] from [date] is still outstanding. Let me know if you need me to resend or if there are any questions.

## Meeting Preparation

Before client meetings:
- Review project status
- List discussion points
- Prepare visual updates if relevant
- Draft agenda to share in advance

After meetings:
- Summarize decisions and action items
- Send recap email within 24h
- Update project board


path: deliverables.md
content: # Deliverables Workflow

## Production Process

```
INPUT → DRAFT → REVIEW → REVISION → APPROVAL → DELIVERY
  ↑                         ↓
  └──── Feedback loop ──────┘
```

## From Input to Draft

When creating any deliverable:

1. **Gather inputs:**
   - Client brief and preferences (from client file)
   - Reference materials and examples
   - Brand guidelines if applicable
   - Relevant prior work

2. **Create structured draft:**
   - Follow agency template if one exists
   - Include all required sections
   - Mark placeholders clearly: [NEEDS INPUT]
   - Add notes for human review: <!-- question about X -->

3. **Self-review before presenting:**
   - Does it match the brief?
   - Is it complete (no missing sections)?
   - Is the quality acceptable for client eyes?

## Deliverable Types

### Reports and Documents
- Structure: Executive summary → Details → Recommendations
- Include visuals (charts, diagrams) where data supports
- Provide both detailed and one-page versions

### Presentations
- One idea per slide
- Minimize text, maximize visual
- Include presenter notes
- Build narrative arc: problem → approach → solution → results

### Creative Assets
- Provide multiple variations for client choice
- Include usage specs (sizes, formats, colors)
- Document any assets used (fonts, stock)

### Code/Technical
- Include README with setup instructions
- Document environment requirements
- Provide QA checklist
- Test before delivery

## Review Process

Before human reviews:
- Check against brief requirements
- Run through QA checklist for this type
- Identify weak spots and flag them

Human reviews and provides feedback:
- Apply changes
- Note patterns for future improvement
- Update templates if relevant

## Revision Management

Track revisions:
```markdown
### Version History
- v1: Initial draft [date]
- v2: Applied client feedback [date] — changes: X, Y, Z
- v3: Final approved [date]
```

Revision limits:
- State revision rounds in proposal
- Track usage per project
- When limit reached, quote additional rounds

## Multi-Format Adaptation

When one piece of content needs multiple formats:

**Example: Article → Social**
- Article (full piece)
- LinkedIn post (key insight + CTA)
- Twitter thread (main points)
- Instagram carousel (visual summary)
- Email newsletter blurb

Adapt each for platform:
- Length constraints
- Tone differences
- Visual requirements

## Delivery Checklist

Before sending to client:
- [ ] All requirements from brief met
- [ ] Proofread / QA passed
- [ ] Correct formats and file types
- [ ] Clear file naming
- [ ] Cover email drafted
- [ ] Next steps mentioned

After delivery:
- [ ] Confirm client receipt
- [ ] Note delivery in project log
- [ ] Archive final files in client folder
- [ ] Update case study if notable


path: feedback.md
content: # Feedback and Learning System

## Purpose

The agency improves over time by capturing:
- What works with clients
- What causes problems
- Patterns to replicate or avoid
- Estimate accuracy over time

## Knowledge Base Structure

`~/agency/knowledge/`:

```
knowledge/
├── sops/                 # Standard Operating Procedures
│   ├── onboarding.md
│   ├── proposal.md
│   └── delivery.md
├── cases/                # Completed project summaries
│   └── [project-name].md
├── learnings.md          # Accumulated insights
└── estimates-log.md      # Estimate vs actual tracking
```

## After Each Project

Capture in `~/agency/knowledge/cases/[project].md`:

```markdown
# [Project Name]

## Client: [name]
## Type: [project type]
## Duration: [start] to [end]
## Value: [revenue]

## What we did
[Brief description]

## What worked
- [Thing that went well]
- [Another success]

## What didn't work
- [Issue and why]
- [Another problem]

## Key learnings
- [Insight to apply to future projects]

## Would we do it again?
[Yes/No and why — honest assessment]
```

## Estimate Tracking

In `~/agency/knowledge/estimates-log.md`:

```markdown
| Project | Type | Estimated Hours | Actual Hours | Variance | Notes |
|---------|------|-----------------|--------------|----------|-------|
| [name]  | [type] | 40h | 52h | +30% | Client slow to respond |
```

Review quarterly:
- Which project types consistently over/under estimate?
- What causes overruns? (scope creep, client delays, complexity)
- Adjust estimation formulas based on patterns

## Template Updates

When something works well:
- Extract the pattern
- Add to relevant template
- Note why it works

When something fails:
- Document what happened
- Add warning to relevant SOP
- Update checklist to prevent recurrence

## Client Feedback Capture

After project delivery:
- Request feedback (formal or informal)
- Record in client file
- Extract actionable improvements

Feedback to track:
- Would they work with us again?
- What did they value most?
- What could we improve?

## Quarterly Review

Every quarter, review:
1. **Projects completed:** wins, losses, lessons
2. **Estimate accuracy:** adjust formulas
3. **Client retention:** who renewed, who didn't, why
4. **Process improvements:** what to update in SOPs
5. **Team performance:** who's growing, who needs support

Update:
- Rate card if costs changed
- Templates if better versions exist
- SOPs if processes improved


path: onboarding.md
content: # Client Onboarding

## Intake Process

When new client inquiry arrives (email, audio, call notes):

1. **Extract and structure:**
   - Business/project name
   - Core need (what they want done)
   - Budget range (stated or implied)
   - Timeline expectations
   - Decision maker and stakeholders
   - How they found you

2. **Generate structured brief:**
   - Problem statement (what's broken/missing)
   - Success criteria (how we'll know it worked)
   - Scope boundaries (in/out of scope)
   - Constraints (tech, brand, legal, time)
   - Deliverables list with acceptance criteria

3. **Flag red flags:**
   - "ASAP" without clear deadline → clarify actual deadline
   - Scope larger than budget suggests → validate budget range
   - No clear decision maker → identify before proposal
   - Changing requirements during intake → document version
   - Past agency horror stories → probe what went wrong

## Discovery Questions by Agency Type

**Marketing/Content:**
- Current channels and performance
- Brand guidelines and assets
- Competitor examples they like/dislike
- Internal approval process

**Development:**
- Existing tech stack
- User volumes expected
- Integration requirements
- Maintenance expectations

**Design/Creative:**
- Brand assets available
- Examples they like (moodboard)
- Stakeholder approval chain
- Usage rights needed

**Consulting:**
- Who commissioned this and why now
- Previous attempts to solve this
- Data/access available
- Implementation capacity after recommendations

## Client Folder Setup

Create `~/agency/clients/[client-slug].md`:

```markdown
# [Client Name]

## Status: [prospect|active|past]
## Start date: [date]
## Primary contact: [name, email]

### Brand/Voice Notes
<!-- Tone, terminology, preferences -->

### Projects
<!-- List with dates and outcomes -->

### History Log
<!-- Key interactions, decisions, issues -->
```

## Red Flag Response Templates

**Budget mismatch:**
> Based on the scope described, our typical investment range is [X-Y]. Let me know if we should adjust scope to fit [their budget] or if there's flexibility on budget.

**Unclear decision maker:**
> To ensure the project moves smoothly, who will be giving final approval on [deliverables]? I want to make sure they're involved at the right checkpoints.

**Rush request:**
> We can accommodate a faster timeline with a [X]% rush rate. The standard timeline for this scope would be [Y weeks]. Which works better for your situation?


path: pricing.md
content: # Pricing and Proposals

## Rate Card Structure

Maintain in ~/agency/config.md:

```markdown
### Hourly Rates
- Strategy/Senior: $X
- Execution/Mid: $Y
- Junior/Support: $Z

### Project Minimums
- Discovery call: $0 (qualify)
- Small project: $X minimum
- Retainer minimum: $Y/month

### Multipliers
- Rush (<1 week): +50%
- Complex integration: +25%
- Enterprise client: +20%
- Ongoing relationship discount: -10%
```

## Estimation Process

Given a scope:

1. **Break into phases:**
   - Discovery/intake
   - Strategy/planning
   - Execution/production
   - Review/revision rounds
   - Delivery/handoff

2. **Estimate hours per phase:**
   - Be specific: "Homepage design: 6h, inner page template: 3h"
   - Include buffer: 15-20% for scope creep
   - Account for client communication time

3. **Apply multipliers:**
   - Check complexity indicators
   - Check timeline pressure
   - Check client type

4. **Compare to historical:**
   - Search `~/agency/knowledge/` for similar projects
   - Adjust if past estimates were off

## Proposal Structure

Generate PDF with:

```
1. CONTEXT
   - Why they came to us
   - What we heard as the core problem

2. APPROACH
   - How we'll solve it (methodology)
   - Why this approach works

3. DELIVERABLES
   - Specific items they receive
   - Format and quantity

4. TIMELINE
   - Phases with dates
   - Client dependencies/approvals needed

5. INVESTMENT
   - Price (or range)
   - What's included
   - What's not included
   - Payment terms

6. NEXT STEPS
   - How to proceed
   - What we need from them
```

## Pricing Traps

- Don't quote before understanding scope — discovery first
- Don't discount without reducing scope — train clients
- Don't hide revision limits in fine print — state clearly
- Don't underestimate client communication time — it's 20-30% of project
- Don't forget handoff/documentation time

## Version Control

When client requests changes to proposal:
- Save v1 before editing
- Track what changed and why
- Note who requested the change
- If scope reduced, reduce price explicitly

## Historical Comparison

Before finalizing estimate, search:
```
Similar projects in ~/agency/knowledge/:
- What was estimated vs actual
- What caused overruns
- What would we do differently
```


path: projects.md
content: # Project Management

## Project States

```
PROSPECT → PROPOSAL → ACTIVE → DELIVERED → CLOSED
              ↓
           LOST (track why)
```

## Unified Project Board

Maintain in `~/agency/projects/`:

```markdown
# Active Projects

## [Client] - [Project Name]
- **Status:** [phase]
- **Deadline:** [date]
- **Health:** 🟢/🟡/🔴
- **Next action:** [what needs to happen]
- **Blockers:** [waiting on X]
- **Hours:** [used]/[budgeted]
```

## Health Indicators

🟢 **On track:**
- Progress matches timeline
- Client responsive
- Within budget

🟡 **At risk:**
- Behind schedule but recoverable
- Waiting on client >3 days
- 80%+ of budget used with work remaining

🔴 **Problem:**
- Will miss deadline
- Scope creep without budget increase
- Over budget
- Client conflict

## Daily/Weekly Routines

**Daily:**
- Check for stalled projects (no updates >2 days)
- Flag approaching deadlines (<48h)
- Respond to client messages

**Weekly:**
- Generate status for each active client
- Update project board
- Flag projects approaching budget limit
- Plan next week's priorities

## Deadline Management

When deadline approaches:
- 7 days out: confirm on track, identify blockers
- 3 days out: flag anything at risk
- 1 day out: final check, prepare delivery
- Day of: deliver, confirm receipt

When deadline at risk:
- Alert human immediately
- Propose solutions (scope cut, deadline extension, more resources)
- Draft client communication if needed

## Resource Allocation

Track in ~/agency/config.md:

```markdown
### Team Availability
- [Name]: [hours/week available]
- [Name]: [hours/week available]

### Current Allocation
- [Name]: [Project A] 20h, [Project B] 10h
```

When new project comes in:
- Check team capacity
- Flag overallocation
- Suggest timeline based on availability

## Scope Tracking

For each project, maintain:
```markdown
### Original Scope
[from proposal]

### Change Requests
- [date]: [change] - approved/denied - impact: [hours/$]

### Current Scope
[original + approved changes]
```

Alert when:
- Client requests feature not in scope
- Cumulative changes exceed 20% of original scope
- Team suggests scope is larger than estimated


path: team.md
content: # Team Coordination

## Team Database

Maintain in ~/agency/config.md:

```markdown
### Team Members

#### [Name]
- Role: [role]
- Skills: [skill1, skill2]
- Availability: [hours/week]
- Rate: [internal cost/hour]
- Current projects: [list]
- Notes: [preferences, timezone, communication style]

### Freelancers

#### [Name]
- Specialty: [what they're best at]
- Rate: [hourly/project]
- Reliability: [1-5 rating based on history]
- Last worked: [date]
- Notes: [turnaround time, quality notes]
```

## Assignment Logic

When project needs resources:

1. Check required skills
2. Check availability in team database
3. Consider:
   - Skill match (who's best at this?)
   - Load balancing (who has capacity?)
   - Client history (have they worked with this client?)
   - Growth opportunity (stretch assignment?)

4. Propose assignment with reasoning

## Briefing Freelancers/Team

Generate clear briefs:

```markdown
# Brief: [Task Name]

## Context
[Project background, client, deadline]

## Deliverable
[Exactly what's needed]

## Specs
- Format: [file types, dimensions]
- Style: [references, brand guidelines]
- Quantity: [number of items/variations]

## Timeline
- Draft due: [date]
- Final due: [date]

## Reference Materials
[Links or files]

## Don'ts
[Things to avoid specifically]

## Questions?
[Who to ask, how to reach]
```

## Quality Control

Before accepting team/freelancer work:
- Check against brief requirements
- Verify quality meets agency standards
- Note any issues for feedback

If work doesn't meet standards:
- Specific feedback on what needs fixing
- Clear deadline for revision
- Track patterns (repeated issues = don't use again)

## Capacity Planning

Weekly capacity check:
- Sum committed hours by person
- Flag overallocation (>100% capacity)
- Identify underutilization
- Plan ahead for known upcoming projects

When selling new work:
- Check team capacity for proposed timeline
- If full, either extend timeline or plan to hire/outsource

## Communication with Team

**Project kickoff:**
- Share full context (not just task)
- Explain how their piece fits the whole
- Provide all needed materials upfront

**During project:**
- Check in on blockers
- Provide feedback quickly
- Escalate problems early

**Project close:**
- Thank them specifically
- Share client feedback
- Note what worked/didn't for future


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)