papyrus-maximus

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

File Roles

README.md

AGENTS.md

docs/

docs/ARCHITECTURE.md

• 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
\```

• 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

• 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

kebab-case-slug.md

kalshi-hardening-2026-02-23.md

loss-reduction-2026-02-23.md

# [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

• 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

validate → enrich → enqueue → respond

Lifecycle

Before Work

AGENTS.md

docs/ARCHITECTURE.md

docs/plans/*.md

After Work

• 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

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/

   .