papyrus-maximus

Project documentation that stays useful. For humans and agents.

Structure

project/
  README.md          ← humans: what is this, how to run it
  AGENTS.md          ← agents: project rules, stack, commands
  CLAUDE.md          ← symlink → AGENTS.md
  docs/
    ARCHITECTURE.md  ← how the system works (diagrams > text)
    *.md             ← guides, references, anything useful
    plans/           ← specs, execution plans, living docs

That's it. No nested agent zones. No session notes folder.

File Roles

README.md

For humans. High-level only.

No architecture. No internal module descriptions. No detailed folder trees.

AGENTS.md

For coding agents. Under 150 lines.

If it's growing past 150 lines, move content to docs/.

docs/ARCHITECTURE.md

How the system is built. Diagram-first, text-second.

Use mermaid diagrams liberally:

• System context → who talks to what (C4 level 1)
• Component diagram → major modules and boundaries (C4 level 2)
• Sequence diagrams → key flows
• State diagrams → lifecycle of important entities

## System Context

\```mermaid
graph LR
  User --> App
  App --> DB[(PostgreSQL)]
  App --> Queue[Redis]
  Worker --> Queue
  Worker --> ExtAPI[External API]
\```

## Components

| Component | Responsibility | Talks to |
|-----------|---------------|----------|
| API | HTTP handlers, auth | DB, Queue |
| Worker | Background jobs | Queue, ExtAPI |
| CLI | Admin commands | DB |

## Key Flows

\```mermaid
sequenceDiagram
  User->>API: POST /order
  API->>DB: insert order
  API->>Queue: enqueue process_order
  Worker->>Queue: dequeue
  Worker->>ExtAPI: submit
  Worker->>DB: update status
\```

Rules:

• Diagrams > text. If you can draw it, draw it.
• Tables > paragraphs. Component lists, config options, API surfaces.
• Pseudocode > real code. process(order) → validate → enqueue → respond beats a 30-line function that'll change next week.
• No folder trees. They go stale immediately. Describe capabilities and boundaries instead.
• Mention modules by name, not by path. "The worker module handles..." not "src/worker/index.ts handles..."

docs/*.md — Other Material

Anything useful for humans or agents:

• GUIDE.md — walkthrough for common tasks
• API.md — endpoint reference
• DEPLOYMENT.md — how to ship it
• DECISIONS.md — notable past decisions (lightweight ADR: what, why, when — no template ceremony)

docs/plans/*.md — Specs & Execution Plans

Filename convention: kebab-case-slug.md (e.g. kalshi-hardening-2026-02-23.md, loss-reduction-2026-02-23.md). No SHOUTING. Date suffix for at-a-glance staleness detection. Living documents. Specs before code. Updated as work progresses.

# [Feature Name]

## Goal
One sentence.

## Context
Why now? What's the current state? What's wrong with it?

## Design

\```mermaid
graph LR
  ...
\```

| Decision | Choice | Why |
|----------|--------|-----|
| Storage | SQLite | Single machine, no need for Postgres |
| Auth | API key | Internal tool, simplicity wins |

## Pseudocode
\```
on_request(order):
  validate(order.fields)
  enriched = fetch_market_data(order.ticker)
  if enriched.price > order.limit: reject("above limit")
  queue.push(enriched)
  return accepted(order.id)
\```

## Tasks
- [x] Design approved
- [ ] Implement core handler
- [ ] Add validation
- [ ] Write tests
- [ ] Update ARCHITECTURE.md

## Open Questions
- How to handle partial fills? → decided: treat as separate orders

Rules:

• Spec first, code second. Don't start implementation without an approved plan.
• Keep them alive. Check off tasks, update decisions, close questions.
• Delete when done. Completed plans can be archived or removed. They served their purpose.
• One plan per feature/initiative. Don't combine unrelated work.

Writing Principles

Lifecycle

Before Work

Read AGENTS.md, docs/ARCHITECTURE.md, and any relevant docs/plans/*.md. Understand what exists before changing anything.

After Work

Update what changed:

• New component? Update docs/ARCHITECTURE.md diagram.
• Finished a plan task? Check it off in docs/plans/*.md.
• New convention or gotcha? Add to AGENTS.md.
• Plan fully done? Delete or archive it.

Keeper Mode

When invoked explicitly as papyrus-maximus:

1. Ensure structure — AGENTS.md exists, CLAUDE.md symlinked, docs/ and docs/plans/ exist
2. Audit — are docs accurate? Do diagrams match reality? Any stale plans?
3. Fix — update what you can. Create missing diagrams. Trim bloat.
4. Flag — report what needs human attention
5. Trim — AGENTS.md under 150 lines. README under 80 lines. Move overflow to docs/.