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
Workflow: Single Prompt/Instruction
- Define boundaries first — What can the agent do? What requires approval?
- Identify context needs — What files/knowledge are required? Link them, don't inline.
- Structure into phases — Break into steps. Add checkpoints where decisions need validation.
- Add validation gates — "Present plan and seek approval before proceeding"
- Size appropriately — One concern per artifact. If too large, decompose.
Prompt Structure Pattern
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:
- Decompose the behavior — What distinct concerns exist?
- Map to primitive types — See primitives.md
- Design the hierarchy — What's project-wide vs. domain-specific?
- Plan composition — How do primitives chain together?
- 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
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:
Consult the [architecture](./docs/arch.md) for system context.
Agent loads only when needed.
Validation Gates:
**STOP:** Present implementation plan and seek approval before writing code.
Scoped Boundaries (in .agent.md frontmatter):
tools: ['file_read', 'file_write', 'run_tests']
# Note: no deployment tools
Explicit Hierarchy:
# Root AGENTS.md
All code must have tests.
# backend/AGENTS.md
Use pytest. Coverage minimum 80%.