putio-frontend-dev

put.io frontend development

Apply shared put.io frontend engineering defaults after the target repository's own guidance and code precedent.

Start

1. Read every filesystem AGENTS.md that applies from the target repo root to

the files being changed, including untracked files. Then inventory tracked auxiliary guidance with git ls-files '*AGENTS.md' '*SKILL.md'.

1. Discover tracked project-local SKILL.md files under .agents/skills/,

.claude/skills/, or skills/. Read the frontmatter and apply only the task-matching skills; ignore dependency and vendored trees.

1. Read the README.md sections and docs that cover the area being changed.

Target-repo guidance and skills override this shared skill.

1. Identify the repo kind, stack, verify entrypoint, delivery target, and

runtime proof surface.

1. Select only the references required for the task.

Reference map

• Feature code, parsing, state, errors, components, and testing:

frontend defaults

• README, CONTRIBUTING, SECURITY, and agent-facing docs:

top-level docs

• CI, verify, publishing, deployment, and release shape for packages and apps:

delivery model

• TypeScript package and app setup:

TypeScript defaults

• Machine tools, peer clones, agent worktrees, readiness check:

environment setup

• Local development secrets and CI credential boundaries:

secrets

• Secret-bearing release, signing, publishing, and deployment:

release security

• Browser, native, TV, emulator, simulator, and device proof:

test harness

• Shared test-account browser authorization:

test harness pattern

• CLI-backed harness discovery, auth, reads, and writes:

CLI harness contract

Markdown links navigate this skill bundle. Other paths shown in the references, such as .github/pull_request_template.md, name files to create or inspect in the target repository.

Repositories

• repos.json lists put.io repositories; frontend-owned entries

list frontend in owns.

• Fields: name is the local folder, repo the GitHub remote, path the

canonical checkout, owns the responsible teams, visibility the documentation boundary, topics the GitHub topic set (optional), mode whether the team's workspace tooling manages the checkout.

• An entry with several teams in owns is shared. In putdotio/.github,

frontend work stays in the frontend-* workflows; in putdotio/agent-skills, in the putio-* skills.

• Peers sit under one folder, default ~/projects/putdotio/. Missing path:

gh repo clone <repo> <path>, or the clone loop in environment setup.

• Check visibility before quoting anything across repos; private content

stays out of public ones.

• For tasks that span all frontend repos: iterate the entries whose owns

includes frontend, enter each root, read its AGENTS.md, run its own verify.

Knowledge base

• Lives in the put.io Notion workspace, Frontend hub; read it through the

Notion MCP.

• Holds Products, Specs, Design, Engineering (Delivery model, Release

security, Secrets management, Third-party services inventory), Architecture decisions, and Guides.

• Read it before product, spec, release, or secrets decisions.

Shared defaults

• Parse external input at the boundary and derive types from the validated

contract.

• Model bug-sensitive flows with explicit states and exhaustive transitions.
• Keep expected errors typed and actionable; bound unexpected failures without

blanking unrelated UI.

• Keep effects at adapters and leaves so render trees remain pure.
• Avoid type escape hatches that weaken the contract.
• Accept usernames, passwords, and current one-time-password codes only on an

official put.io website. Keep the long-lived TOTP seed inside the authorized secret provider that generates the current code. CLI, mobile, TV, extension, harness, and other clients must delegate account authorization to the website through OAuth or device-link flows and handle only the resulting codes or tokens.

• Let repo-local guidance and established code override shared defaults.
• Keep verification logic in repo-owned commands that CI calls. Preserve an

established task graph; use one verify entrypoint when creating a new lane.

• Deliver from trusted main or validated release refs only after verification.
• Finish in-scope edits, checks, and fixes without pausing for approval; ask

before anything destructive, paid, public, or outside the task, such as deploys, publishes, secret or provider changes, external writes, and force-pushes.

• Exercise user-visible behavior in the real browser, app, simulator, emulator,

or device surface when one exists.

• Before a proof command launches a runtime, install cleanup and record whether

it started that exact target. On every exit, stop only targets it started and confirm their absence; preserve pre-existing targets.

Workflow

1. Inspect the current implementation, docs, scripts, workflows, and proof

surface before proposing a shape.

1. Apply the smallest relevant shared defaults and preserve working repo

conventions unless evidence shows they are wrong.

1. Record non-obvious code conventions in the nearest AGENTS.md; keep user,

contributor, distribution, and security documentation in their canonical homes.

1. Keep workflow orchestration thin and put repeatable build, verify, deploy,

and smoke logic behind repo-owned commands.

1. Select the owner's documented checks for the affected behavior and its

dependents. Run the full canonical gate when owner policy requires it, shared inputs changed, or focused coverage is uncertain. Preserve separate installed-package, downstream-consumer, browser, and device proof where those boundaries matter. Command discovery does not authorize live actions. Fix failures and refresh affected proof. Reuse passing proof while its source, inputs, and environment remain valid; a new turn or handoff alone does not require another run. Name unavailable proof and its exact blocker.

1. Report changed behavior, verification, proof artifacts, risks, and remaining

gaps.

Boundaries

• SDK repositories belong to the dedicated SDK development workflow, including

their docs, verification, release, and delivery shape.

• Operating the putio CLI as a files, downloads, transfers, auth, or storage

consumer belongs to the CLI's consumer guidance. Frontend harnesses use the installed CLI through the CLI harness contract.

• Repository policy, generic GitHub Actions hardening, build-tool migrations,

bootability repair, and independent code review are outside this skill; it supplies put.io frontend domain guidance to whichever workflow does that work.

• Keep machine-specific facts, credentials, account details, and private

support context out of this public skill; the repository registry carries names, remotes, canonical paths, owners, visibility, topics, and mode only.