AGENTS.md
Product direction
Old Fella is an iPhone-first, native SwiftUI client for the Bluesky service, with a minimum deployment target of iOS 27. The goal is a polished, dependable daily-use app with a deliberately small interface—not a feature-complete social network client. Follow Apple’s current Human Interface Guidelines and make the app feel at home on iOS. Use a system-native, content-first visual direction; use Liquid Glass selectively when it improves navigation or interaction, never as decoration or at the expense of readability, accessibility, or content.
Keep the feed and its posts central. Prefer familiar native controls, clear navigation, readable text, and useful loading, empty, and error states over custom chrome. Support system appearance, Dynamic Type, VoiceOver, and other standard accessibility behavior.
Fluidity and speed are core design goals: interactions should feel immediate, scrolling should stay smooth, and startup and navigation should be fast. Keep runtime work efficient, avoid blocking the main thread, and pay attention to image loading and rendering so media does not make the app feel sluggish. Favor measured, practical optimizations that preserve simple, maintainable code.
MVP scope
- Support iPhone first.
- Support iPad with side-by-side feed and notification columns.
- Sign in to and sign out of one existing Bluesky account. Do not include account creation or account switching in the MVP.
- Show Following or a saved custom feed using the order supplied by Bluesky. Do not reorder posts client-side.
- Provide a top-left feed button and a sheet with saved feed names and avatars. Remember the selected feed across restarts. If the selected feed no longer exists, return to Following.
- Support creating posts and replies, liking and unliking, reposting and undoing reposts, quote-posting, and following and unfollowing accounts.
- Let users save and remove posts from the three-dot menu. Show saved posts in server order. Open Saved Posts from the iPhone tab bar or the iPad floating button.
- On iPhone, open Settings from the signed-in user's profile toolbar.
- Show profiles and post detail with reply threads. Tapping a link to a post inside Old Fella must navigate to that post inside the app.
- Support search for accounts and posts, including a filter for the user's own posts.
- Show notifications inside the app. Do not add push notifications.
- Respect user moderation choices. Support blocking, muting, and reporting. Hide posts that match muted words and posts from muted or blocked accounts.
- To reduce distractions, hide posts and their context when a content label would require the user to reveal them.
- Support online use with understandable loading, empty, and failure states and a way to retry. Do not promise offline browsing.
Media and links — hard constraints
- Show attached images and GIFs inline. Open videos in the existing full-screen player.
- Show quoted post context unless the user hides it or moderation hides it. Let users open the original post inside Old Fella when moderation allows it.
- Do not render other embeds or embed cards.
- Show external links as text links, not preview cards.
- Do not fetch, proxy, or rehost media just to create previews or playback.
Explicitly out of scope for the MVP
Do not add these without a deliberate product decision: push notifications, feed discovery, account creation, multiple-account switching, guaranteed offline reading, additional custom video or GIF players, or external link preview cards. The feed picker lists saved custom feeds only.
Architecture and implementation guidance
- First inspect the repository and available Xcode project before changing code. Do not assume targets, deployment versions, dependencies, file paths, or project structure that are not present.
- Keep the implementation small and idiomatic to SwiftUI. Separate presentation from Bluesky network/session work enough to test behavior and evolve it; avoid speculative frameworks and layers.
- Keep feed loading behind a small boundary. Reuse the timeline UI for Following and saved custom feeds. Do not add feed discovery or feed-management controls.
- Use Bluesky app-password sign-in for the MVP. Ask for the dedicated app password, never the account’s primary password; store credentials with iOS secure storage and never log secrets. Keep the active account/session boundary clear so multiple accounts can be added later without building account switching now.
- Keep Bluesky-specific networking isolated from view code. Represent posts, authors, and interactions in testable types or services appropriate to the project’s actual structure.
- Use ATProtoKit for AT Protocol and Bluesky integration. Before upgrading or replacing it, make sure that it supports the iOS 27 minimum deployment target. Keep it behind the app’s service boundary. Do not expose library types directly to SwiftUI views.
- Use native URL handling for links. Preserve in-app navigation for Old Fella post links; do not let the media rule turn post links into external-only navigation.
- Provide clear failure feedback for network-backed actions. Avoid presenting an action as successful when the request failed.
- Add focused tests for important data and interaction behavior, including media presentation, links, and moderation choices.
Agent-driven, terminal-first development
- Treat agent-driven development as a project goal. Make routine development tasks understandable and runnable from a terminal so the developer rarely needs to open Xcode.
- Keep the root
Justfileminimal: provide targets for installing dependencies, build-only iteration, running in a simulator, running on a connected device, and running UI tests in a simulator. Do not add extra convenience targets unless a real need appears. - Declare Homebrew-managed dependencies in a root
Brewfileand have the dependency-install target usebrew bundle install --file Brewfile. Bootstrapjustitself once with Homebrew; do not make ajustrecipe install its own command runner. The target must fail with clear guidance if Homebrew or Xcode is missing. - Apple’s Xcode toolchain, Swift,
sourcekit-lsp, SDKs, and simulator runtimes are Apple-managed; check for required components and explain how to install or select missing components rather than claiming Homebrew installed them. - Put non-trivial task logic in small, readable, checked-in scripts rather than relying on hidden IDE state or asking an agent to reconstruct long command lines. Scripts must fail clearly, report useful errors, and avoid destructive side effects unless explicitly requested.
- Use Apple’s standard command-line tooling (such as
xcodebuild) underneath the targets. Keep the terminal workflow usable by both agents and a person working directly in a shell; routine build, simulator, and device workflows should not depend on opening Xcode. - Maintain the Xcode project through
project.ymland XcodeGen. Prefer the simplest setup that supports reliable terminal builds and tests. Do not add project generators, package managers, or extra build layers without a demonstrated need. Use Xcode when visual inspection or debugging benefits from it. - Provide a UI-test target that agents can run from the terminal on a simulator, with a minimal
just testworkflow backed by Apple’s standard tooling. - Run tests focused on the change. Do not run the entire UI test suite unless the user asks for it or the change requires it.
- For agent testing, use
just test-agentwith the appropriate test selection. This target does not explicitly open Device Hub, but Apple tooling can still open windows or affect a running simulator. - Run
just simonly when the user explicitly asks to open the simulator. If a change needs visual review, explain that it needs review. - When the user asks to install the app on a physical device, always use
just device-releasewith the appropriate device UID. - UI tests must run deterministically without live Bluesky credentials or network access. Provide a test-only way to supply predictable service responses, and cover important user flows through the app’s visible interface.
- Keep UI tests focused on end-to-end behavior and use unit tests for detailed data and service logic. Make test failures and results visible in terminal output.
- For Swift symbol-aware navigation, use Apple's
sourcekit-lspwhen available.
Subagents and model use
- Use subagents when work is meaningfully independent, parallelizable, or benefits from isolated research or review. Handle small, tightly coupled tasks directly rather than adding delegation overhead.
- Give each subagent a bounded assignment with the goal, relevant context, scope and file ownership, constraints, and the expected result. For parallel code changes, use separate worktrees when available or assign strictly disjoint files; require agents to preserve unrelated edits.
- Choose the smallest capable configured Polytoken subagent/model for the work. Prefer
general-purpose-minifor mechanical, repetitive, or narrowly scoped tasks; usegeneral-purposefor complex judgment, cross-cutting work, or when a mini agent cannot complete the assignment. Useresearcherfor evidence gathering andplan-reviewerfor reviewing a proposed plan when those configured agents are available. - Do not assume a model or subagent name is configured in every Polytoken environment. Use available configured options; do not force a model override unless the user requests it or the environment’s instructions require one.
- Treat subagent output as evidence, not approval or verified truth. Check consequential findings and changes, run relevant verification, and integrate results in the main task context before reporting completion.
Required writing style
- Every agent MUST load and follow the project-local
simple-englishskill at.polytoken/skills/simple-english/SKILL.mdbefore writing text. - This rule applies to every agent-authored response and text artifact, including chat replies, documentation, commit messages, pull request descriptions, code comments, error messages, and agent instructions.
- Apply the skill’s Reply rules to every chat response. Apply its Document rules to all persistent prose, including commit messages. Use Plain mode unless the user requests STE, ASD-STE100, or compliance.
- Keep code, identifiers, commands, flags, file paths, quoted text, product names, and source facts unchanged when applying these writing rules.
Commits
- Before the first change on each branch, record its starting
HEAD. Track session commit hashes across turns. - When the user says the session is done, run squash-session-commits once.
- Every agent MUST commit completed repository changes before ending a task.
- Every agent MUST use atomic commits. Each atomic commit contains one logical change and its required supporting files.
- When multiple logical changes are present in the repository, split them into separate commits.
- Include related tests and required project updates in the same commit as the change.
- Stage only the files or parts of files that belong to the commit. Leave unrelated user changes untouched.
- Before each commit, review the staged diff and make sure that the relevant checks pass.
- Every agent MUST use Conventional Commits for every commit, without exception. Use the format
<type>(optional-scope): <description>(or<type>!:/<type>(scope)!:for breaking changes); for example,docs: clarify media rules. This applies to all changes, including documentation, build tooling, maintenance, and small fixes. Never create a commit with a non-conventional message.
Issue titles
- Every issue title MUST use Conventional Commits format:
<type>(optional-scope): <description>. - Use
featfor a new feature andfixfor a defect. Use another standard type when it fits the issue. - Keep the description short and specific. For example:
feat(ipad): add side-by-side columnsandfeat(search): add post and people search.
Planning note
Release timing is intentionally open because this is a toy project, not a work project with a launch deadline. Verify the existing project and current platform requirements before making implementation decisions; do not treat a guess as an agreed product requirement.