Intent File Formats¶

Yilan scans the following files in each repo and extracts outstanding sections. The parser reads ## headings and the items beneath them — not individual dot-points.

roadmap.md / ROADMAP.md¶

Purpose: Planned features, milestones, future work. Parser rule: ## headings with at least one outstanding item underneath.

Rules¶

Yilan reads each ## heading and the checklist items beneath it (until the next ## or EOF).
A heading is outstanding (shown on the board) unless it is done.
A heading is done when:
Its text contains ✅, OR
All checklist items beneath it are - [x] AND at least one item exists.
Each outstanding heading is rendered as: {heading text} (N of M open).
✅ is stripped from the heading text before rendering.
Only ## headings are scanned; #, ###, and deeper levels are ignored.
Items must start at column 0 — indented checklist items (- [ ] …) are skipped.

Example¶

## Phase 1 — Core ✅

- [x] Scaffold package
- [x] Add caching layer

## Phase 2 — Polish

- [x] Add `--dry-run` flag
- [ ] Write installation docs
- [ ] Add `--overview` support

Yilan output: Phase 2 — Polish (2 of 3 open)

(Phase 1 is skipped — ✅ in heading.)

Agent sub-prompt for roadmap updates¶

When adding or updating planned work in roadmap.md, use this format:

## Phase or milestone name
- [ ] Task not yet started or in progress
- [x] Completed task

Rules:
- Group related tasks under a ## heading (phase, milestone, or theme).
- Use - [ ] for incomplete work, - [x] for done.
- Add ✅ to the ## heading once all tasks in that group are complete: ## Phase 1 ✅
- One line per item — no sub-bullets, no prose paragraphs.
- Update entries in place; do not append duplicate headings.

improvements.md¶

Purpose: Enhancements, optimisations, nice-to-haves. Parser rule: same as roadmap — ## headings, checklist items.

Example¶

## Performance

- [ ] Cache DNS lookups
- [x] Switch to connection pooling

## UX

- [ ] Colour-code severity levels in output

Yilan output: Performance (1 of 2 open), UX (1 of 1 open)

Agent sub-prompt for improvements¶

When recording improvements or enhancements in improvements.md, use this format:

## Area or theme
- [ ] Improvement not yet made
- [x] Improvement already made

Rules:
- Group related items under a ## heading (component, area, or theme).
- Use - [ ] for pending work, - [x] for done.
- Add ✅ to the ## heading once all items in the group are complete: ## Performance ✅
- One line per item — no sub-bullets, no prose.
- Update entries in place; do not append duplicate headings.

security-audit.md / Security-Audit.md / Security_Audit.md¶

Purpose: Security findings, risks, hardening tasks. Parser rule: ## headings with checklist items — same as roadmap.md.

Use - [ ] for open/unresolved findings and - [x] for resolved or accepted ones. Keep detailed analysis in a separate prose document; this file is the tracking list only.

Rules¶

Same as roadmap.md: ## headings, - [ ] / - [x] checklist items.
A heading is done when all items are - [x], or when its text contains ✅.
Each outstanding heading is rendered as: {heading text} (N of M open).

Example¶

## Critical ✅

- [x] F-01 — SSRF in webhook handler  *(resolved: URL scheme/host validation added)*
- [x] F-02 — Hardcoded API key  *(resolved: moved to env var)*

## High

- [x] F-03 — Insecure direct object reference  *(resolved: ownership check added)*
- [ ] F-04 — Missing auth on /admin endpoint

## Accepted

- [x] F-05 — No rate limiting on public read endpoint  *(accepted: low-risk, revisit at scale)*

Yilan output: High (1 of 2 open)

(Critical and Accepted are skipped — all items [x].)

Agent sub-prompt for security reviews¶

When commissioning a security review from an agent, prepend this instruction block to ensure findings are recorded in the correct format:

After completing the review, record all findings in security-audit.md using this format:

## {Severity}   ← use: Critical / High / Medium / Low / Accepted
- [ ] F-XX — Short description of unresolved finding
- [x] F-XX — Short description  *(resolved: one-line explanation)*
- [x] F-XX — Short description  *(accepted: one-line rationale)*

Rules:
- One line per finding — no prose, no sub-bullets.
- Mark resolved findings [x] with a brief italic note: *(resolved: what was done)*.
- Mark accepted risks [x] with rationale: *(accepted: why risk is tolerated)*.
- Add ✅ to the ## heading once every finding in that group is closed:
  ## Low ✅
- Do not put detailed analysis here — that belongs in a separate prose audit document.
- Update entries in place when findings are resolved; do not append duplicates.

TODO.md¶

Purpose: Short-term tasks, reminders, miscellaneous work items. Parser rule: flat checklist — no headings; renders as a single summary line.

TODO.md typically has no ## headings. Yilan counts all - [ ] (open) and - [x] (done) items at column 0 and renders a single summary rather than individual entries.

Rules¶

Outstanding items: - [ ] Item text
Completed items: - [x] Item text
Items must start at column 0.
Rendered as: Todo: N of M open
Omitted from the board if no checklist items are found.

Example¶

- [ ] Reply to issue #42 about Windows path handling
- [x] Update changelog for 0.3.0
- [ ] Investigate flaky test in CI

Yilan output: Todo: 2 of 3 open

Agent sub-prompt for TODO updates¶

When adding items to TODO.md, use this format:

- [ ] Thing to do
- [x] Thing already done

Rules:
- Flat list only — no ## headings.
- Use - [ ] for open items, - [x] for done.
- Items must start at column 0 — no indentation.
- One line per item.
- Check off or remove items when done rather than leaving stale entries.

NOTES.md¶

Purpose: Decisions, context, open questions worth tracking. Parser rule: same as roadmap — ## headings, checklist items.

Rules¶

Use ## Heading to group action items you want Yilan to surface.
Add - [ ] … under a heading for items to track; - [x] … to mark done.
Prose paragraphs and regular bullets (- note text) are ignored by Yilan.
A heading with all items checked (or containing ✅) is suppressed.

Example¶

## Open Questions

- [ ] Confirm cattrs handles optional fields correctly in Python 3.13
- [ ] Benchmark serialisation vs hand-rolled dicts

Yilan output: Open Questions (2 of 2 open)

Agent sub-prompt for notes¶

When recording decisions, open questions, or tracked context in NOTES.md, use this format:

## Topic or question group
- [ ] Open question or unresolved action
- [x] Resolved question or completed action  *(optional: brief resolution note)*

Rules:
- Group related items under a ## heading.
- Use - [ ] for unresolved items, - [x] for resolved ones.
- Prose paragraphs and plain bullets (- note text) are ignored by yilan — use
  checkboxes only for items you want tracked on the board.
- Add ✅ to the ## heading once all items in the group are resolved: ## Open Questions ✅
- One line per item.
- Update entries in place; do not append duplicate headings.

Summary table¶

File	Heading level	Item syntax	Done / suppressed
roadmap.md	`##`	`- [ ] / - [x]`	`✅` in heading, or all items `- [x]`
improvements.md	`##`	`- [ ] / - [x]`	same
security-audit.md	`##`	`- [ ] / - [x]`	`✅` in heading, or all items `- [x]`
TODO.md	none (flat)	`- [ ] / - [x]`	summary only: `Todo: N of M open`
NOTES.md	`##`	`- [ ] / - [x]`	same as roadmap

Universal rules (all files):

Only ## headings are scanned (except TODO.md which has no headings).
Items must start at column 0 — no leading spaces or tabs.
✅ is stripped from heading text before rendering.
Headings with no items underneath are ignored.
No cross-file deduplication — headings from multiple files are listed in file order.