# Prose Architect

> Design PROSE-compliant AI-native code in Markdown. Use when (1) Writing prompts, instructions, or agent definitions (2) Designing multi-primitive AI systems from requirements (3) Decomposing mega-prompts into composable primitives (4) Auditing prompts/instructions for reliability issues. PROSE = Progressive Disclosure, Reduced Scope, Orchestrated Composition, Scoped Boundaries, Explicit Hierarchy Use when this capability is needed.

- Skill: `tomevault-io/prose-architect` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/prose-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/prose-architect/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/prose-architect

---


# PROSE Architect

Design AI-native Markdown artifacts that are reliable, scalable, and composable.

## Quick Compliance Check

Before writing, verify the artifact will satisfy:

| Constraint | Question |
|------------|----------|
| **P** Progressive Disclosure | Does context load just-in-time via links, not all upfront? |
| **R** Reduced Scope | Is scope sized for one concern? Can phases get fresh context? |
| **O** Orchestrated Composition | Are you composing small primitives, not building a mega-prompt? |
| **S** Scoped Boundaries | Are tools, knowledge scope, and approval gates explicit? |
| **E** Explicit Hierarchy | Do local rules inherit/override global rules appropriately? |

For constraint details: [constraints.md](references/constraints.md)

## Workflow: Single Prompt/Instruction

1. **Define boundaries first** — What can the agent do? What requires approval?
2. **Identify context needs** — What files/knowledge are required? Link them, don't inline.
3. **Structure into phases** — Break into steps. Add checkpoints where decisions need validation.
4. **Add validation gates** — "Present plan and seek approval before proceeding"
5. **Size appropriately** — One concern per artifact. If too large, decompose.

### Prompt Structure Pattern

```markdown
You are [role with domain focus].

## Context
Consult [relevant file](./path/to/file.md) for [specific purpose].

## Steps
1. [First phase with clear deliverable]
2. [Second phase]
3. **Checkpoint:** Present [output] and seek user approval before proceeding.
4. [Execution phase after approval]

## Boundaries
- CAN: [explicit capabilities]
- CANNOT: [explicit restrictions]
- APPROVAL REQUIRED: [what needs human sign-off]
```

## Workflow: Multi-Primitive System

When designing a system with multiple coordinated primitives:

1. **Decompose the behavior** — What distinct concerns exist?
2. **Map to primitive types** — See [primitives.md](references/primitives.md)
3. **Design the hierarchy** — What's project-wide vs. domain-specific?
4. **Plan composition** — How do primitives chain together?
5. **Define handoff points** — Where does one primitive's scope end?

### System Architecture Pattern

```
project/
├── AGENTS.md                      # Project-wide principles
├── .github/
│   ├── instructions/
│   │   ├── frontend.instructions.md   # applyTo: "**/*.tsx"
│   │   └── backend.instructions.md    # applyTo: "**/*.py"
│   ├── prompts/
│   │   └── feature-workflow.prompt.md # Orchestrates the flow
│   └── chatmodes/
│       └── architect.chatmode.md      # Planning, no execution tools
└── domain/
    └── AGENTS.md                  # Domain-specific rules (inherits root)
```

## Primitive Selection

| Need | Primitive | Key Property |
|------|-----------|--------------|
| Persistent rules | `.instructions.md` | `applyTo` pattern scoping |
| Reusable workflow | `.prompt.md` | Invokable task template |
| Bounded persona | `.agent.md` | Tool restrictions + role |
| Distributable capability | `SKILL.md` | Auto-discovery, portable |
| Reference knowledge | `.context.md` | On-demand loading |
| Session memory | `.memory.md` | Persists across sessions |

Full guide: [primitives.md](references/primitives.md)

## Anti-Pattern Detection

When reviewing existing artifacts, watch for:

| Symptom | Violation | Fix |
|---------|-----------|-----|
| 500+ line prompt | Orchestrated Composition | Decompose into primitives |
| All docs loaded upfront | Progressive Disclosure | Use links for just-in-time loading |
| No validation gates | Scoped Boundaries | Add checkpoints before destructive actions |
| Same rules everywhere | Explicit Hierarchy | Use `applyTo` patterns + nested AGENTS.md |
| "Do everything" agent | Reduced Scope | Split into phased workflow or multiple agents |

## Key Mechanisms

**Progressive Disclosure:**
```markdown
Consult the [architecture](./docs/arch.md) for system context.
```
Agent loads only when needed.

**Validation Gates:**
```markdown
**STOP:** Present implementation plan and seek approval before writing code.
```

**Scoped Boundaries (in .agent.md frontmatter):**
```yaml
tools: ['file_read', 'file_write', 'run_tests']
# Note: no deployment tools
```

**Explicit Hierarchy:**
```markdown
# Root AGENTS.md
All code must have tests.

# backend/AGENTS.md  
Use pytest. Coverage minimum 80%.
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/danielmeppiel) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->