Skip to main content

​
File Structure: Information Hierarchy

​
Overview

The file structure is the information hierarchy of your marketing organization. Inspired by The Phoenix Project, it’s designed to:
  • Make work visible
  • Prevent marketing debt (orphaned files, inconsistency)
  • Enable temporal tracking (research evolves over time)
  • Create audit trails (strategy backed by research)
  • Support progressive disclosure (load only what’s needed)
Think of it as the filing cabinet system of a company—everything has a place, relationships are clear, and nothing gets lost.

​
Complete Directory Structure

/workspace-root/
├── .claude/                          ← Architecture configuration
│   ├── output-styles/                ← Primary agent behavior
│   ├── agents/                       ← Sub-agent definitions
│   ├── skills/                       ← Reusable capabilities
│   └── commands/                     ← Workflow triggers
│
├── /strategy/                        ← Brand bible (polished, client-ready)
│   ├── STRATEGY.md                   ← Progressive disclosure entry point
│   ├── /core/                        ← Foundational brand elements
│   ├── /messaging/                   ← Value props, pillars
│   ├── /voice/                       ← Tone guidelines
│   └── /audience/                    ← Personas, psychographics
│
├── /research/                        ← Research domains (temporal, raw)
│   ├── /{domain}/                    ← Research domain (e.g., category-landscape)
│   │   ├── RESEARCH.md               ← Progressive disclosure guide
│   │   ├── /data/                    ← Input materials
│   │   ├── /execution/               ← Temporal research runs
│   │   │   └── /{date}/              ← Date-stamped execution
│   │   │       ├── PLAN.md
│   │   │       ├── TODO.md
│   │   │       └── notes.md
│   │   └── /exports/                 ← Deliverables
│   │
├── /docs/                            ← Architecture documentation (you are here)
│
├── .mcp.json                         ← Tool integrations (MCP config)
├── .env                              ← API keys (not committed)
├── .env.example                      ← API key template (committed)
├── CLAUDE.md                         ← Project instructions for agents
└── MANIFESTO.md                      ← Philosophy and vision

​
Directory Purposes

​
/.claude/ (Architecture Configuration)

Purpose: Defines the system’s behavior and capabilities Contents: 
.claude/
├── output-styles/
│   └── marketing-operations-manager.md  ← Primary agent system prompt
│
├── agents/
│   ├── brand-analyst.md                 ← Sub-agent: Research specialist
│   ├── content-writer.md                ← Sub-agent: Content specialist
│   └── campaign-strategist.md           ← Sub-agent: Campaign specialist
│
├── skills/
│   ├── conducting-market-research/
│   │   ├── SKILL.md
│   │   ├── competitive-analysis.md
│   │   └── customer-research.md
│   │
│   ├── writing-brand-consistent-content/
│   │   ├── SKILL.md
│   │   ├── voice-guidelines.md
│   │   └── content-types/
│   │
│   └── orchestrating-projects/          ← Core skill (infra team)
│       └── SKILL.md
│
└── commands/
    ├── /onboarding/                     ← Domain: Onboarding workflows
    │   ├── build-messaging.md
    │   └── discover-brand-story.md
    │
    └── /campaigns/                      ← Domain: Campaign workflows
        └── launch-sequence.md
Who owns:
  • Infrastructure team: output-styles/, core skills/, meta commands
  • Marketing architects: agents/, domain skills/, domain commands/
Key principle: This is the org chart implementation—agents, skills, and workflows

​
/strategy/ (Brand Bible)

Purpose: Polished, client-ready brand strategy that agents reference for brand consistency Contents: 
strategy/
├── STRATEGY.md                        ← Entry point (progressive disclosure)
│
├── /core/
│   ├── narrative.md                   ← Brand story (tension, belief, promise)
│   └── positioning.md                 ← Market position
│
├── /messaging/
│   ├── pillars.md                     ← Core brand themes
│   └── value-propositions.md          ← Value props by audience
│
├── /voice/
│   ├── tone-guidelines.md             ← Voice principles
│   └── vocabulary.md                  ← Approved/banned terms
│
└── /audience/
    └── personas/
        ├── agency-owner.md
        └── in-house-marketer.md
Characteristics:
  • Polished - Client-facing quality
  • Timeless - Not date-stamped (evolves via version control)
  • Backed by research - Footnotes reference /research/
  • Progressive disclosure - STRATEGY.md guides to specific files
Example from narrative.md: 
[^productivity-paradox-narrative]: Customer research (William),
`/research/discover-customer-insight/execution/customer-insights-transcript-analysis.md:34-53`
This creates an audit trail from strategy claims back to research evidence.

​
/research/ (Research Domains)

Purpose: Temporal research that backs up strategy and provides ongoing insights Structure: 
research/
├── /category-landscape/               ← Research domain
│   ├── RESEARCH.md                    ← Progressive disclosure guide
│   │
│   ├── /data/                         ← Input materials
│   │   ├── transcripts/
│   │   ├── surveys/
│   │   └── datasets/
│   │
│   ├── /execution/                    ← Temporal research runs
│   │   ├── /2025-10-20/               ← First research run
│   │   │   ├── PLAN.md
│   │   │   ├── TODO.md
│   │   │   └── analyst-notes.md
│   │   │
│   │   └── /2025-10-25/               ← Follow-up research
│   │       ├── PLAN.md
│   │       ├── TODO.md
│   │       └── updated-analysis.md
│   │
│   └── /exports/                      ← Deliverables
│       └── final-report.md
│
└── /competitor-analysis/              ← Another research domain
    └── ... (same structure)
The Three-Folder Pattern:
  1. /data/ - Input materials (what we provide)
    • Customer interview transcripts
    • Survey results
    • Industry reports
    • Datasets
  2. /execution/ - Process (work happens here)
    • Date-stamped research runs (temporal)
    • PLAN.md and TODO.md for visibility
    • Sub-agent work notes
    • Interim analysis
  3. /exports/ - Output (deliverables)
    • Final research reports
    • Presentations
    • Conversation exports
Why date-stamped executions?
  • Research is temporal - markets change, competitors evolve
  • You can compare 2025-10-20 vs 2025-10-25 to see evolution
  • Historical context preserved (not overwritten)

​
/research/ vs /strategy/ Relationship

Flow: 
/research/                    /strategy/
(Raw, temporal)              (Polished, timeless)
    ↓                             ↑
Informs                      References
    ↓                             ↑
Research findings    →    Strategy claims (with footnotes)
Example: Research: /research/discover-customer-insight/execution/2025-10-15/insights.md 
## Key Finding
Marketing strategists report "working just as hard" despite AI tools.
William: "I'm spending still the same amount of time on a computer,
if not more than before." (transcript line 42)
Strategy: /strategy/core/narrative.md 
## The Tension
Marketing strategists are using more AI tools than ever—and working
just as hard.[^productivity-paradox]

[^productivity-paradox]: Customer research (William),
`/research/discover-customer-insight/execution/2025-10-15/insights.md:42`
This creates:
  • ✅ Audit trail (strategy is defensible)
  • ✅ Research visibility (not lost in folders)
  • ✅ Version control (strategy evolves based on new research)

​
RESEARCH.md (Progressive Disclosure)

Purpose: Guide agents to relevant research within a domain Example: /research/category-landscape/RESEARCH.md 
# Category Landscape Research

## Overview
This domain tracks the marketing automation and AI tools landscape.

## Available Research

### Latest Research (2025-10-25)
Most recent analysis: `/execution/2025-10-25/`

Key findings:
- AI slop increasing (140% YoY per study)
- SaaS fatigue cited by 67% of respondents
- Ownership narrative resonating with early adopters

### Historical Research
- `/execution/2025-10-20/` - Initial landscape scan
- `/execution/2025-08-15/` - Pre-launch market sizing

## Data Sources
See `/data/` for:
- Industry reports → `/data/reports/`
- Customer interviews → `/data/transcripts/`
- Survey results → `/data/surveys/`

## Research Methodologies
For how we conduct this research:
- Competitive analysis → See SKILL: Conducting Competitive Analysis
- Customer insights → See SKILL: Analyzing Qualitative Data

## When to Update
This research should be refreshed:
- Quarterly (market landscape shifts)
- When major competitor launches
- Before strategy updates
Agents can navigate directly to what they need.

​
STRATEGY.md (Progressive Disclosure)

Purpose: Guide agents to relevant strategy within brand bible Example: /strategy/STRATEGY.md 
# Brand Strategy

## Overview
This is the complete brand strategy for [Brand Name]. All content
must align with these strategic foundations.

## Quick Navigation

### Need brand voice?
See: `/voice/tone-guidelines.md`

### Need messaging themes?
See: `/messaging/pillars.md`

### Need brand narrative?
See: `/core/narrative.md`

### Need positioning?
See: `/core/positioning.md`

### Need audience personas?
See: `/audience/personas/`

## Using This Strategy

### For Content Generation
1. Read `/voice/` for tone
2. Read `/messaging/` for themes
3. Apply relevant content framework

### For Campaign Planning
1. Read `/core/positioning.md` for market position
2. Read `/messaging/value-propositions.md` for audience-specific value
3. Read `/audience/personas/` for targeting

### For Brand Decisions
1. Read `/core/narrative.md` for foundational beliefs
2. Validate against research in `/research/`

## Validation Status
Last updated: 2025-10-16
Backed by research in: `/research/discover-customer-insight/`

## Related Research
This strategy is informed by:
- `/research/founder-interview/` - Vision and philosophy
- `/research/discover-customer-insight/` - Customer validation
- `/research/category-landscape/` - Market positioning

​
File Naming Conventions

​
General Rules

✅ Use kebab-case:
  • brand-narrative.md
  • value-propositions.md
  • agency-owner-persona.md
❌ Avoid:
  • Brand Narrative.md (spaces)
  • brand_narrative.md (underscores)
  • brandNarrative.md (camelCase)

​
Special Files

UPPERCASE.md = Entry points (progressive disclosure):
  • STRATEGY.md
  • RESEARCH.md
  • SKILL.md
  • PLAN.md
  • TODO.md
These files are “tables of contents” that guide navigation.

​
Work Visibility Files

​
PLAN.md

Created by: Operations Manager (during plan meta command) Purpose: Map out approach before execution Location: /research/{domain}/execution/{date}/PLAN.md or project-specific Structure: 
# Plan: [Task Name]

## Objective
[Clear goal]

## Approach
1. Step one
2. Step two
3. Step three

## Resources
- Skills: [which skills will be used]
- Agents: [which sub-agents will be involved]
- Files: [which strategy/research files referenced]
- Tools: [which external tools needed]

## Estimated Effort
[Time/complexity estimate]

## Approval
- [ ] Marketing Architect approval required before implement

​
TODO.md

Created by: Operations Manager (during implement meta command) Purpose: Track work in progress Location: Same as PLAN.md Structure: 
# TODO: [Task Name]

## Tasks
- [x] Task 1 - COMPLETED
- [x] Task 2 - COMPLETED
- [ ] Task 3 - IN PROGRESS
- [ ] Task 4 - PENDING
- [ ] Task 5 - PENDING

## Progress
40% complete

## Blockers
None currently

## Next Steps
1. Complete Task 3
2. Begin Task 4
3. Final review
Why this matters (Phoenix Project):
  • Work is visible (not hidden in agent memory)
  • Progress is trackable
  • Blockers are flagged early
  • WIP (work in progress) is managed

​
Information Flow

​
Research → Strategy → Content

1. Research Domain (/research/category-landscape/)
   ↓
   Findings captured in /execution/{date}/
   ↓
2. Strategy (/strategy/core/narrative.md)
   ↓
   References research with footnotes
   ↓
3. Content Generation
   ↓
   Agents read strategy → generate brand-consistent content
This creates a chain of trust:
  • Content is backed by strategy
  • Strategy is backed by research
  • Research is backed by data
  • Nothing is made up or generic

​
Preventing Marketing Debt

Marketing debt = orphaned files, inconsistent outputs, lost research

​
How File Structure Prevents It

1. Everything has a place
  • Strategy files → /strategy/{domain}/
  • Research → /research/{domain}/
  • Work in progress → PLAN.md, TODO.md
2. Temporal execution preserves history
  • Research isn’t overwritten, it’s versioned (/execution/{date}/)
  • You can see evolution over time
  • Nothing is lost
3. Progressive disclosure creates navigation
  • STRATEGY.md, RESEARCH.md guide agents
  • No guessing where files are
  • Reduces duplication
4. Audit trails create accountability
  • Strategy footnotes → Research files
  • Research cites → Data sources
  • Clear lineage of every claim

​
Best Practices

✅ Good: 
/strategy/voice/
├── tone-guidelines.md
├── vocabulary.md
└── examples.md
❌ Bad: 
/strategy/voice-tone.md
/strategy/voice-vocabulary.md
/content/voice-examples.md  ← Scattered

​
2. Use Progressive Disclosure Entry Points

Every major directory should have an entry point:
  • /strategy/STRATEGY.md
  • /research/{domain}/RESEARCH.md
  • .claude/skills/{skill}/SKILL.md

​
3. Date-Stamp Temporal Work

Research executions: 
/execution/2025-10-20/
/execution/2025-10-25/
Not: 
/execution/latest/  ← Gets overwritten
/execution/v1/      ← Not clear when it happened

​
4. Reference, Don’t Duplicate

✅ Good: Strategy file references research: 
[^claim]: See /research/category-landscape/execution/2025-10-20/findings.md
❌ Bad: Copy-pasting research into strategy (creates drift)

​
5. Keep PLAN.md and TODO.md Visible

Put them at the top level of execution: 
/execution/2025-10-20/
├── PLAN.md      ← Easy to find
├── TODO.md      ← Easy to find
└── analyst-notes.md

​
Common Questions

​
Q: Where should campaign work live?

Answer: Depends on the type: Research for campaign: 
/research/campaign-name/
├── RESEARCH.md
├── /data/
├── /execution/{date}/
└── /exports/
Campaign deliverables: Consider creating /campaigns/ directory (not in current structure, but you can add it).

​
Q: Can I add new top-level directories?

Yes, but carefully. Consider:
  • Does it fit the information hierarchy?
  • Is it distinct from /strategy/ and /research/?
  • Will agents know to look there?
Examples that make sense:
  • /campaigns/ - Active campaign work
  • /content-library/ - Published content archive
  • /templates/ - Reusable templates

​
Q: Should I version control everything?

Yes (except .env with API keys). Git ignore: 
.env
node_modules/
*.log
Commit:
  • All /strategy/
  • All /research/
  • All .claude/ (except sensitive data)
  • PLAN.md, TODO.md

​
Q: How do I prevent strategy files from getting too long?

Use progressive disclosure: If /strategy/voice/tone-guidelines.md gets too long: 
/strategy/voice/
├── index.md           ← Overview
├── principles.md      ← Core principles
├── platforms/
│   ├── twitter.md     ← Platform-specific
│   └── linkedin.md
└── examples/
    └── do-dont.md

​
What’s Next

Now that you understand the file structure, see how work flows through it: Or explore the underlying principles:
  • Principles - Phoenix Project influence, progressive disclosure
“The file structure isn’t just organization—it’s how your system thinks.”