AGENTS.md

Guide for AI agents (Claude Code, Codex, etc.) working in this repo. CLAUDE.md is a symlink to this file.

What this is

Logical Thinking Process (LTP) / Issue Tree app — a tool to decompose a top-level claim into a tree of sub-claims and accumulate evidence (annotations from source docs) against that stable tree scaffold. Collaboration of Rufus Pollock + David Joseph.

Where to look

Conventions

• Never line-wrap Markdown. One paragraph is one line, however long. This holds everywhere — files in this repo, GitHub issue and PR bodies, and comments. Hard-wrapped prose makes diffs useless (change three words and the whole paragraph re-flows), makes editing in a browser textarea miserable, and buys nothing: every renderer and editor soft-wraps already. Wrap only where the line break is content — list items, table rows, code blocks, and deliberate <br>-style breaks in verse or address blocks. If you are reflowing a paragraph you are about to edit anyway, unwrap it; do not reflow whole files just to convert them, because that buries the real change.
• Skills live in top-level skills/<name>/ so they're usable outside Claude Code (e.g. Codex). .claude/ is gitignored (local-only, see .gitignore), so to let Claude Code discover them, wire the symlinks locally:

  mkdir -p .claude/skills
  ln -s ../../skills/reason-commons .claude/skills/reason-commons
  ln -s ../../skills/ltp-project .claude/skills/ltp-project
  ln -s ../../skills/ltp-visualize .claude/skills/ltp-visualize
  

  skills/ltp-project/ is canonical in this repo (as of 2026-09-28); the copy in Promise-Foundation/reason-commons is older, so never copy it over this one. The bun run check:import step was removed here (TODO in its SKILL.md, bead reasoncommons-vc0).
• Codex skills are discovered under .agents/skills/. The repository tracks .agents/skills/reason-commons, .agents/skills/ltp-project and .agents/skills/ltp-visualize as symlinks to the same skills/<name>/ directories, so edits stay shared between Claude Code and Codex. In the Codex app, invoke one explicitly, such as $reason-commons, or let its description trigger it automatically. Restart Codex if a newly added skill does not appear in the Skills sidebar.
• Toy example first. Validate any AI skill against the gold data in claim-tree-annotation.md before touching real applications (e.g. Second Renaissance).
• Keep motivation.md (why + SCQH) current; it's referenced from README.md. Plan-of-work tracking (streams, next actions) lives in GitHub issues, not a repo file.
• Concern boundaries. Shared reasoning lives in ltp/, project working material in docs/, installable packages and their helpers/tests in skills/, runnable software with its configuration/tests/operating instructions in apps/, deliberate public content in website/, and cross-project utilities in scripts/. See the root README.md map and docs/product/repository-boundaries.md. Private funding material retains its existing private locations; a public Git repository is still public outside the website root.
• Explainers layout. Finished scrolling pieces live at website/explainers/<slug>/index.html, with the series landing page at website/explainers/index.md and shared scroller.css/scroller.js beside it. Scripts, critiques, visual scripts and retired source articles live at docs/marketing/explainers/<slug>/; never put them in the publishing root. Read skills/scrollable-explainer/SKILL.md before drafting. Link to the explicit <slug>/index.html; bare folders only resolve automatically for Markdown. Public prose and assets use their existing URL paths even though the source is now under website/.
• Explicit website exports. Keep motivation.md, claim-tree-annotation.md, skills/README.md and ltp/ltp-model.yaml canonical in their project locations. python3 scripts/export-website.py refreshes their declared public copies; do not edit those generated copies. python3 scripts/check-website.py checks export drift, the publishing boundary, local links/assets and preserved routes. Add a deliberate export rather than a symlink out of website/; never publish the working collaboration YAML or a private draft.
• No blank lines inside raw HTML in Markdown. A blank line ends the raw HTML block as far as the Markdown parser is concerned. Anything after it that's indented four spaces or more — which inline SVG almost always is — then parses as an indented code block, and the figure renders on the page as literal markup. Keep <figure>…</figure> and <svg>…</svg> unbroken:

  <figure>
  <svg viewBox="0 0 640 260" role="img" aria-label="…">
    <rect x="20" y="60" width="90" height="90"/>
    <rect x="140" y="60" width="90" height="90"/>   <!-- no blank line above -->
  </svg>
  <figcaption>Figure 1 · …</figcaption>
  </figure>
  

  Group the SVG with comments or <g> elements if you want visual separation. This bites silently: the page still returns 200, so it only shows up if you look at it. After changing any Markdown that embeds HTML, check the rendered output for escaped markup — curl -s <url> | grep '&lt;rect\|&lt;svg' should come back empty. Allow a moment after fl for the rebuild; a fetch made mid-rebuild can return a stale page and mislead you either way.
• Beads (bd) tracks agent-executable work plans (e.g. Explainers v2); GitHub issues stay the place for project-level planning. Issues labelled human are gates only Rufus closes.
• Before implementation, show a typed proposal and record typed acceptance. Follow the Change proposal template in skills/reason-commons/references/responses.md. Every user request to change project code, documents, configuration or skills, including “fix it” and small changes, requires a complete user-visible proposal before implementation. Name the reasoning served and its standing, list concrete node/link/backlog updates, show their topology and state validation. Read-only inspection may come first. Give each proposal an ID and revision, then wait for the user's unambiguous typed acceptance of that displayed version and scope; the initial request is insufficient. Explain that this wait follows the user's acceptance-recording rule. Record the human identity, exact reply, scope, proposal version and recording time in the working YAML's top-level change_acceptances log, save the intended tree updates and validate before editing implementation files. Material revisions need fresh typed acceptance; an already-accepted version needs no repeat approval. Final implementation reports use Change result and retain the reasoning trace and acceptance receipt. Next step recommends an action or inquiry that has not been performed. These rules apply even when the skill was not explicitly invoked. Implementation approval is distinct from reasoning endorsement; ordinary conversational capture, reasoning endorsement and recording an already-given acceptance need no additional proposal or approval.
• Every pull request names its reasoning and recorded approval. Fill the sections of .github/pull_request_template.md, including when writing the body yourself. Under Reasoning this serves, name the node or link IDs in ltp/rufus-david-collab/reason-commons.yaml the change supports. Under Reasoning changes, show the generated, visible Mermaid diagrams of the actual YAML diff. Keep the complete Tree updates list in a closed <details> block, or "None" for no node/link edits when meaningful tree work is recorded through backlog. python3 skills/reason-commons/scripts/check_pr_trees.py ltp/rufus-david-collab/reason-commons.yaml --base origin/main --suggest --format markdown generates both sections. Under Accepted change proposals, cite each saved receipt as - `proposal-id` revision 1 by `participant-id` . Record the proposal's exact covered paths as approved_paths before implementation; cited receipts must cover all changed files and node/link IDs. Run the checker with --body-file against the PR base; CI validates diagram source, collapsed list completeness, state, receipts, declaration coverage and preservation of earlier receipts. Inspect the actual GitHub rendering before reporting completion. Review implementation meaning and the actual approval separately. Backlog work belongs in the proposal, scope and result even when no node/link changes appear. Opening or merging a PR does not endorse proposed reasoning, and an unchanged approved scope needs no repeat acceptance. If no node fits, ask rather than citing one loosely.
• Resume collaboration through its handoff. Before choosing a reasoning topic for the Rufus–David collaboration, read bd show reasoncommons-a4l and its current work bead, then skills/reason-commons/SKILL.md and ltp/rufus-david-collab/reason-commons.yaml. Follow docs/beads-reasoning.md: Beads owns session priorities, ownership and task completion; the conversational YAML owns reasoning, acceptance and reasoning backlog. Refresh the existing START HERE bead at the end of a meaningful session. Closing a bead never endorses a claim or resolves a challenge automatically. Implementation work arising from tree sessions goes into separate beads and separate sessions. If bd is unavailable, read the saved .beads/issues.jsonl as a fallback and report that it may be stale; do not silently replace an existing database or start a second task list.
• There is exactly one NEXT.md, at the repo root. Don't create per-folder ones.
• Preview before pushing to live. main serves the live site (reasoncommons.com, Flowershow site ltp-issue-trees). The publishing root is website/; run python3 scripts/export-website.py, python3 scripts/check-website.py, then fl website --yes for the separate preview at https://reasoncommons-preview-rufuspollock.flowershow.me. website/.flowershow retains that preview target. Publishing this folder avoids traversing agent skill links and project working material. The initial migration needs a coordinated production root-directory switch to /website; follow docs/product/repository-boundaries.md before merging or deploying it. Do not change production just to test rendering. Preview asset delivery has served stale CSS/JS despite reporting a sync. If a preview looks wrong, compare the actual bytes, for example md5 -q website/explainers/scroller.css against curl -sL https://reasoncommons-preview-rufuspollock.flowershow.me/explainers/scroller.css | md5 -q. A stale preview is not evidence that the source is broken. See https://github.com/flowershow/flowershow/issues/1363.
• Checking phone width. Use node scripts/phone-check.mjs <url> [out.png], which emulates a 375px device over the DevTools protocol and lists anything overflowing. Plain chrome --headless --window-size=375,… screenshots lie: headless Chrome won't size a window below 500px, so you get a cropped 500px layout with text apparently clipped at the right edge. That artefact is what GH #20 was first reported from.
• Root README.md and AGENTS.md retain their exact uppercase names for tooling. Published prose uses lowercase names where appropriate; the public homepage is website/README.md, and root motivation.md has an explicit public export at /motivation.

Changelog

This repo follows the life-itself changelog convention (CONVENTION.md). One file per entry in website/changelog/, named YYYY-MM-DD-slug.md, with frontmatter date, title, authors and promote: false. Flowershow builds the /changelog timeline from the folder, so there is no index file to maintain. Screenshots go in website/changelog/images/. Authors are handles matching a profile page in website/people/ (e.g. rufus-pollock → website/people/rufus-pollock.md, with title and a GitHub avatar). At a session checkpoint, if something reader-facing shipped, draft an entry: default to none for routine sessions, and link to the live feature where there is one. Fetch and follow the convention for the full rules.