# AgentStack File Conventions Spec v0.1

The OS layer above the Claude Code marketplace. This document specifies which files each AgentStack skill **reads** and **writes**, so the skills cooperate without you re-explaining your project.

A skill is just a markdown prompt. A workflow OS is a set of skills that read each other's outputs.

> Free to copy, fork, or steal. The spec is the product; the polish is the upgrade.

---

## Why a spec

You have six skills. They work in isolation. Tomorrow you install a seventh and it doesn't know what the previous six wrote. So you re-explain your project to it. Every. Time.

The fix is a *file convention*: an agreement about which paths in your repo each skill writes to and reads from. With a convention, the seventh skill is plug-and-play. The next skill knows where to look.

This is the AgentStack convention. It is opinionated, simple, and version-controlled. Use it as-is, fork it, or invent your own — the point is to have one.

---

## Top-level directories

```
your-repo/
├── .claude/
│   ├── skills/                # SKILL.md files (you write these)
│   ├── agents/                # Specialist agents
│   └── settings.local.json    # Local settings (gitignored)
├── docs/
│   ├── releases/              # Release notes (skill-written)
│   ├── adr/                   # Architecture Decision Records
│   ├── support/               # Support reply drafts
│   └── pricing/               # Pricing-page drafts
├── research/
│   ├── competitors/           # Competitor briefs
│   └── customers/             # Customer-interview synthesis
├── marketing/
│   ├── threads/               # Launch thread drafts
│   ├── posts/                 # Long-form drafts (DEV.to, blog)
│   └── headlines/             # Headline iterations
├── checklists/
│   └── shipping-checklist.md  # Output of pre-deploy run
└── CHANGELOG.md               # Source of truth for all release skills
```

---

## Skill contracts

Each skill declares: trigger phrases, files it reads, files it writes, and the side effect.

### `shipping-checklist`

| | |
|--|--|
| **Triggers on** | "ready to ship", "ship it", "pre-deploy" |
| **Reads** | `package.json`, `.env*`, `migrations/`, `tests/`, last 10 commits |
| **Writes** | `checklists/shipping-checklist.md` (timestamped append), `docs/releases/v<x>.<y>.<z>.md` (draft if release detected) |
| **Side effect** | Surfaces blocking items in chat. Does not run tests itself — just reports their state. |

### `launch-thread-writer`

| | |
|--|--|
| **Triggers on** | "draft launch thread", "twitter thread for vN.N" |
| **Reads** | `docs/releases/<latest>.md`, `CHANGELOG.md`, `marketing/headlines/*` |
| **Writes** | `marketing/threads/<release-slug>.md` |
| **Side effect** | None. Output is markdown only. |

### `support-reply-drafter`

| | |
|--|--|
| **Triggers on** | "draft a reply to this email", "support reply" |
| **Reads** | The email body (provided in chat), `docs/support/voice.md` (your voice spec), last 3 entries in `docs/support/replies/*` |
| **Writes** | `docs/support/replies/<timestamp>-<subject-slug>.md` |
| **Side effect** | None. |

### `pricing-page-generator`

| | |
|--|--|
| **Triggers on** | "draft a pricing page", "tier pricing" |
| **Reads** | `README.md`, `docs/pricing/*.md` (any prior drafts), product description from chat |
| **Writes** | `docs/pricing/<timestamp>.md` (3-tier markdown with anchors + FAQ block) |
| **Side effect** | None. |

### `architecture-decision-recorder`

| | |
|--|--|
| **Triggers on** | "record an ADR", "ADR for X" |
| **Reads** | `docs/adr/*` (last numbered ADR) |
| **Writes** | `docs/adr/ADR-NNN-<slug>.md` (auto-incremented number) |
| **Side effect** | None. |

### `competitor-deep-dive`

| | |
|--|--|
| **Triggers on** | "deep dive on <domain>", "competitor brief for <X>" |
| **Reads** | The target's public surface (web fetch). `research/competitors/*.md` for prior context. |
| **Writes** | `research/competitors/<domain>-<YYYY-MM-DD>.md` |
| **Side effect** | None. |

---

## State-sharing patterns

The skills cooperate via the files. Three patterns matter:

### 1. The release fork

```
shipping-checklist → docs/releases/v0.7.0.md (draft)
                  ↓
launch-thread-writer reads docs/releases/v0.7.0.md
                  ↓
launch-thread-writer → marketing/threads/v0.7.0.md
```

You never re-explain what shipped. Whatever shipping-checklist wrote IS what launch-thread-writer reads.

### 2. The decision trail

```
architecture-decision-recorder → docs/adr/ADR-007-postgres.md
                              ↓
next architecture-decision-recorder run reads ADR-006, ADR-007
                              ↓
auto-numbers next as ADR-008, references prior decisions where relevant
```

The ADR sequence becomes a reasoning history. The next ADR knows the last one.

### 3. The voice anchor

```
support-reply-drafter reads docs/support/voice.md (you write this once)
                        +
                        last 3 docs/support/replies/*
                        ↓
output matches established tone
```

You don't tell the skill your voice. It reads it from disk every time.

---

## Adding your own skill

To plug into the OS, your custom skill should:

1. **Declare a trigger phrase** in its `SKILL.md` frontmatter that doesn't collide with the existing six.
2. **Read at least one file** that another skill writes (otherwise you're isolated).
3. **Write to a directory** in the convention (or a new top-level dir, ideally introduced via an ADR).
4. **Not delete or rewrite files written by other skills.** Append, don't overwrite.

If your skill follows these four rules, it composes with the existing pack.

---

## Versioning

This document is versioned. v0.1 is the starting set; conventions will evolve as use cases demand.

Breaking changes (renaming a directory, changing a file format) bump the major version. Additive changes (new skill, new file) bump the minor. Read the changelog at the bottom before installing skill updates.

---

## License

Released under MIT. Take it. Fork it. Sell a Notion-flavored version. Just don't claim you invented the convention before AgentStack — there's a public race-state.json with timestamps.

---

## Related artifacts

- **Power Pack** (the six skills implementing this spec): [agentstackhq.gumroad.com/l/power-pack](https://agentstackhq.gumroad.com/l/power-pack) — pay what you want from $0
- **Free deploy-checker** (one skill, full source): [agentstack-ecru.vercel.app/free](https://agentstack-ecru.vercel.app/free)
- **Public race scoreboard** (3-way race to $10K): [agentstack-ecru.vercel.app/race](https://agentstack-ecru.vercel.app/race)

---

## Changelog

- **v0.1 — 2026-05-04** — Initial spec. Six skills, three sharing patterns, four extension rules.