| name | add-payee |
| description | Add a new payee (merchant, person, organization, or UUID) to the correct preludes journal file, maintaining strict lexicographical order. |
Skill: Add Payee
Payee directives must always be added to a preludes/ journal file, never to monthly or yearly journals. If you encounter a strict payee error (e.g., 'payee ... has not been declared'), resolve it by adding the payee to the appropriate preludes/ file as described below.
This skill describes how to add a new payee to the ledger system.
When to Use
- When a new merchant, person, organization, or UUID payee is encountered in a transaction or needs to be registered for future use.
Example & guidance: See ./examples.md for a short example of adding a payee to preludes/self.journal. Validate with bun run format and bun run check after adding.
Steps
-
Determine the correct preludes file
- All payee directives must be placed in a
preludes/ journal file, never in a monthly or yearly journal.
- Most payees go in
preludes/self.journal.
- If the payee is specific to an alternative or other scenario, use the appropriate
preludes/*.journal file.
-
Locate the payee section
- Find the block of lines starting with
payee in the chosen preludes file.
-
Insert the new payee
- Add a line:
payee <payee-name-or-UUID>
- Place the new payee in strict lexicographical (ASCII/Unicode) order within the payee section.
- When adding, check the entire payee section for correct placement and move any out-of-order entries if found.
-
Validation
Note: Use the canonical formatting and validation workflow: see .agents/instructions/developer-workflows.instructions.md and .agents/instructions/common-workflows.instructions.md for steps and examples (prefer bun run format and bun run check).
Anti-Patterns
- Never add payees to monthly or yearly journals. Always use a
preludes/ file.
- Inserting payees out of order, or failing to correct existing order mistakes.
- Payees must be in strict lexicographical (ASCII/Unicode) order. When adding, scan the entire payee section and correct any out-of-order entries proactively.
