Skip to content

Service Requirements Template

Purpose: Standard folder structure for any service/deliverable to be agentified. Each service folder is self-contained and portable — contains everything needed to build an agent.

Key principle from Lydia: "Three golden examples, and those golden examples have to be inputs AND outputs and any feedback in the middle."

Folder Structure

references/by-division/{division}/services/{service-name}/
├── README.md                      # ⭐ Status dashboard + completeness checklist
├── requirements.md                # User stories, acceptance criteria, activation triggers
├── methodology.md                 # Step-by-step process, decision rules (div-level)
├── data-sources.md                # Tools accessed, schemas, sample queries
├── constraints.md                 # Edge cases, known limitations, fallback behaviors
│
├── golden-examples/               # 2-3 complete examples
│   ├── example-1/
│   │   ├── context.md             # Client context, project brief, challenge
│   │   ├── inputs/                # Data files, screenshots, source materials
│   │   ├── outputs/               # Final deliverable (anonymized)
│   │   └── feedback.md            # Team lead feedback, iterations, what made it excellent
│   ├── example-2/
│   │   └── ...
│   └── example-3/
│       └── ...
│
├── qa-testing/                    # Test cases for validation
│   ├── test-case-1.md             # Input + expected output
│   └── test-case-2.md
│
└── source-materials/              # Original files (preserved, not modified)
    ├── ninjacat-agent/            # NinjaCat markdown files
    ├── videos/                    # Walkthrough recordings (or links)
    ├── training/                  # Training outlines, guru cards
    └── code/                      # Custom actions, scripts

README.md Template (Status Dashboard)

Every service folder MUST have this README. It serves as:

  1. Status dashboard — what's complete, what's missing
  2. Completeness checklist — agent can parse and validate
  3. Quick reference — human entry point
# {Service Name} — Requirements Package

**Division**: {SEO | Analytics | PDM | Creative | CS | Operations}  
**Status**: {🔴 Missing Core | 🟡 Partial | 🟢 Ready for Build}  
**Last Updated**: YYYY-MM-DD  
**Owner**: {Name}

---

## Completeness Checklist

| Category | Status | Location | Notes |
|----------|--------|----------|-------|
| **User Stories** | ⬜/✅ | `requirements.md` | WHO/WHAT/WHY/HOW/WHEN |
| **Methodology** | ⬜/✅ | `methodology.md` | Step-by-step, decision rules |
| **Data Sources** | ⬜/✅ | `data-sources.md` | Tools, schemas, sample queries |
| **Golden Example 1** | ⬜/✅ | `golden-examples/example-1/` | Context + Inputs + Outputs + Feedback |
| **Golden Example 2** | ⬜/✅ | `golden-examples/example-2/` | Context + Inputs + Outputs + Feedback |
| **Golden Example 3** | ⬜/✅ | `golden-examples/example-3/` | (Optional but recommended) |
| **QA Test Cases** | ⬜/✅ | `qa-testing/` | Input + expected output |
| **Constraints** | ⬜/✅ | `constraints.md` | Edge cases, fallback behaviors |

**Minimum viable**: User Stories + Methodology + 2 Golden Examples + Data Sources

---

## Quick Reference

**What this service does**: {One-line description}

**Primary deliverable**: {What artifact does the practitioner produce?}

**Activation triggers**: {Keywords/phrases that should activate this agent}

**Dependencies**:
- MCP servers: {BigQuery, DataForSEO, Wrike...}
- Other skills: {writing-standards, quality-standards...}

---

## Golden Example Summary

| Example | Client Type | Challenge | Excellence Criteria |
|---------|-------------|-----------|---------------------|
| Example 1 | {Industry} | {Problem} | {What made it excellent} |
| Example 2 | {Industry} | {Problem} | {What made it excellent} |
| Example 3 | {Industry} | {Problem} | {What made it excellent} |

---

## Migration Notes

**Source**: {NinjaCat agent, existing command, new build...}  
**Migration status**: {Not started | In progress | Complete}  
**Target command**: `plugins/divisions/{div}/commands/{command}.md`  
**Target skill resources**: `plugins/divisions/{div}/skills/{div}-methods/resources/`

File Templates

requirements.md

# {Service Name} — Requirements

## User Stories

### Primary Story

**WHO**: {Practitioner persona — SEO Strategist, Account Lead, Analyst...}  
**WHAT**: {Deliverable type — audit report, analysis deck, recommendations...}  
**WHY**: {Business value — client impact, efficiency gain, quality improvement}  
**HOW measured**: {Success metrics — methodology compliance, client approval, time saved}  
**WHEN activates**: {Trigger phrases — "content audit", "analyze page", "search landscape"}

### Secondary Stories

{Additional user stories if service supports multiple use cases}

---

## Acceptance Criteria

For this service to be considered complete, the agent MUST:

1. [ ] {Specific measurable criterion}
2. [ ] {Specific measurable criterion}
3. [ ] {Specific measurable criterion}
...

---

## Activation Triggers

**Keywords**: `["keyword1", "keyword2", "keyword3"]`

**Intent patterns**: 
- `"(analyze|audit|review).*(content|page|site)"`
- `"search landscape"`

**File patterns**: `["**/audits/**", "**/deliverables/**"]`

methodology.md

# {Service Name} — Methodology

> **Important**: This is the **division-level** methodology, not individual SME preferences.  
> Source: {Guru card, training doc, team lead consensus...}

---

## Process Overview

{High-level description of the workflow}

---

## Step-by-Step Process

### Step 1: {Step Name}

**Purpose**: {Why this step exists}

**Actions**:
1. {Specific action}
2. {Specific action}
3. {Specific action}

**Decision points**:
- IF {condition} → THEN {action}
- IF {condition} → THEN {action}

**Validation**: {How to verify step is complete}

---

### Step 2: {Step Name}

{Same format as above}

---

## Decision Framework

| Situation | Decision | Rationale |
|-----------|----------|-----------|
| {Condition} | {Action} | {Why} |
| {Condition} | {Action} | {Why} |

---

## Quality Gates

| Gate | Criteria | Who Validates |
|------|----------|---------------|
| Draft Complete | {Measurable criteria} | Self |
| Peer Review | {Measurable criteria} | Team member |
| Final Approval | {Measurable criteria} | Team lead / Client |

data-sources.md

# {Service Name} — Data Sources

## Tools Accessed

| Tool | Purpose | Access Method |
|------|---------|---------------|
| {Tool name} | {What data} | {MCP server / API / Manual} |
| {Tool name} | {What data} | {MCP server / API / Manual} |

---

## Schema Reference

### {Data Source 1}

**Location**: {BigQuery table, API endpoint, etc.}

**Key fields**:

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| {field} | {type} | {description} | {example} |

**Sample query**:
```sql
SELECT ...
FROM ...
WHERE ...

Data Freshness

Source Update Frequency Lag Time
{Source} {Daily/Weekly/Real-time} {Hours/Days} 
### constraints.md

```markdown
# {Service Name} — Constraints & Edge Cases

## Known Limitations

| Limitation | Impact | Workaround |
|------------|--------|------------|
| {Limitation} | {What breaks} | {Fallback behavior} |

---

## Edge Cases

### {Edge Case 1}

**Scenario**: {When this happens}

**Detection**: {How agent knows this is happening}

**Handling**: {What agent should do}

**User message**: {What to tell the user}

---

## Error Messages

| Error Condition | User-Facing Message |
|-----------------|---------------------|
| {Condition} | "{Helpful message with next steps}" |

golden-examples/{example}/feedback.md

# {Example Name} — Feedback & Excellence Criteria

## What Made This Excellent

1. {Specific quality attribute}
2. {Specific quality attribute}
3. {Specific quality attribute}

---

## Feedback Received

### From Team Lead

> "{Direct quote or paraphrase of feedback}"

**What was iterated**:
- {Change made based on feedback}
- {Change made based on feedback}

### From Client (if applicable)

> "{Direct quote or paraphrase}"

---

## Outcome

- {Measurable result — traffic recovered, recommendations implemented, etc.}

Migration from Current Structure

The current references/by-division/{division}/build-specs/[DIV] Service Name/ folders contain the raw materials. To standardize:

  1. Keep source-materials/: Move existing files (videos, NinjaCat markdown, etc.) into source-materials/
  2. Extract methodology: From NinjaCat INSTRUCTIONS.md → methodology.md
  3. Create golden-examples/: From QA Testing outputs, organize with context + inputs + outputs + feedback
  4. Add README.md: Create status dashboard using template above
  5. Fill gaps: Use checklist to identify what's missing, gather from SMEs

Agent Validation Command

An agent should be able to validate completeness:

## /validate-service-requirements

**Input**: Path to service folder

**Output**: 
- Checklist status (✅/⬜ for each category)
- Missing items list
- Recommendation for what to gather next
- Confidence score (0-100%) for build-readiness