folio

Imported from Misoto22/folio (AGENTS.md). Install upstream with npx skills add Misoto22/folio. Copyright stays with the author.

Additional Conventions Beyond the Built-in Functions

As this project's AI coding tool, you must follow the additional conventions below, in addition to the built-in functions.

Delivery contract

• [HAR-CORE-001] MUST — Reconnaissance. Read the relevant code, configuration, instructions, and repository state before proposing or changing behavior. Match the repository's established patterns unless its source of truth requires a correction.
• [HAR-SCOPE-001] MUST — Scope. Keep work inside the user's requested outcome. Read-only discovery may expand enough to establish truth; external writes and materially different changes require explicit authority.
• [HAR-VERIFY-001] MUST — Evidence. Run the command that proves each claimed result and report complete, blocked, drifted, and not-installed states separately. A partial or inconclusive check is not a pass.

Code Review Rules

• [HAR-REV-001] MUST — Evidence-backed findings. Report only evidence-backed P0 or P1 findings with tight file and line references and the applicable stable rule ID when one exists; suppress style-only or speculative comments.

Release automation

• [HAR-REL-001] MUST — Automated releases. Cut every actively developed repository's releases through the fleet release bot: the reusable Misoto22/ci release workflow running release-please in manifest mode as the misoto22-release-bot GitHub App. Derive the version, CHANGELOG.md, and GitHub Release from Conventional Commits; never hand-edit a version field and never move a tag. Configure a multi-package npm workspace with the node-workspace plugin and linked versions so the repository still tags one vMAJOR.MINOR.PATCH.
• [HAR-REL-002] SHOULD — Changelog vocabulary. List only feat, fix, perf, revert, docs, and refactor in changelog-sections. Never list chore, ci, build, test, or style, not even hidden, because release-please then considers those commits for a bump and cuts a patch release for a lone housekeeping commit.

Continuous integration

• [HAR-CI-001] MUST — Linux pull-request gate. Run pull-request checks on Linux runners, declare a concurrency group keyed on the ref with cancel-in-progress for pull requests, and apply path filters wherever a change cannot alter a check's result.
• [HAR-CI-002] MUST — macOS off the pull-request path. Run GitHub-hosted macOS only for tag pushes, scheduled runs, or path-gated platform changes; gate an Apple-platform pull request on a self-hosted runner or a Linux SwiftPM package test instead.
• [HAR-CI-003] MUST — Pinned actions. Reference every third-party action and reusable workflow by full commit SHA with a trailing version comment, and keep those references current through Dependabot's github-actions ecosystem.
• [HAR-CI-004] SHOULD — Required checks by name. Require the repository's own CI job or jobs and pr-title / pr-title in the branch ruleset, and write a reusable-workflow job's check context as <caller job id> / <called job name>.

Git safety

• [HAR-GIT-001] MUST — Isolation. Implement feature work on a feature branch in an isolated worktree when the current checkout contains unrelated work or the task spans repositories.
• [HAR-GIT-002] MUST — Preservation. Preserve unrelated dirty changes. Never reset, discard, or force-push the default branch. Resolve exact targets before destructive actions and prefer recoverable operations.

Rule governance

The uppercase words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described by BCP 14.

• [HAR-GOV-001] MUST — Normative vocabulary. Use uppercase BCP 14 requirement words only when a rule has normative force; do not create additional machine-enforced requirement levels.
• [HAR-GOV-002] MUST — Stable rule identifiers. Treat rule IDs as immutable opaque identifiers; never reuse an ID after renaming, deprecation, retirement, splitting, or merging.
• [HAR-GOV-003] MUST — Time-bounded exceptions. Record every exception with its owner, reason, exact scope, approval, and expiry or review date before relying on it.

Naming baseline

• [HAR-NAME-001] SHOULD — Portable repository names. Use lowercase ASCII kebab-case for repository directories, documentation, and assets by default; preserve ecosystem-native source filenames and record an explicit repository exception when a tool requires another form.
• [HAR-NAME-003] MUST — Release identifiers. Use SemVer vMAJOR.MINOR.PATCH release tags and never move a published release tag or change a historical identifier.
• [HAR-NAME-004] MUST — Environment variable names. Use upper snake case environment variables with a product or domain prefix, and never put secret values in tracked configuration.
• [HAR-NAME-005] SHOULD — Native code identifiers. Follow the language and framework formatter or linter already authoritative in the repository for code identifiers.
• [HAR-NAME-006] MUST — Scoped delivery names. Use <type>(<scope>)/<short-kebab-topic> branches by default, where <type> is a Conventional Commits type (feat, fix, chore, docs, refactor, perf, test, ci, build, revert, or style) and <scope> is a short kebab-case area as in feat(app)/device-auth or fix(api)/rate-limit; keep Conventional Commit subjects in imperative English and imperative English pull-request titles.

Security baseline

• [HAR-SEC-001] MUST — Secret safety. Keep credential values out of source, prompts, logs, fixtures, generated artifacts, and terminal output. Store only references or documented environment-variable names.
• [HAR-SEC-002] MUST — Boundaries. Validate untrusted input at the system boundary, parameterize database queries, redact sensitive data, and expose stable public errors instead of internal details.

Testing baseline

• [HAR-TEST-001] MUST — Behavior tests. New or changed business behavior requires a test that exercises the real boundary and covers the relevant success, edge, and failure paths.
• [HAR-TEST-002] MUST — Repository gate. Before commit or review, run the repository's documented CI-equivalent checks. At minimum, compile or build changed production code when no stronger command exists.

TypeScript

• [HAR-TS-001] MUST — Repository contract. Follow the checked-in package manager, workspace boundaries, compiler settings, lint rules, and test runner. Prefer existing types and components over parallel local abstractions; verify typecheck and the affected test/build path.

@misoto22/folio

• [DESIGN-ARCH-001] MUST — Keep primitives reusable. Tokens and components may serve the public site and admin console but must not absorb either host's routes, data access, or business logic.
• [DESIGN-TOKEN-001] MUST — Preserve token ownership. Change the canonical CSS and TypeScript token sources, then rebuild exported CSS and package artifacts instead of editing dist/.
• [DESIGN-API-001] MUST — Treat exports as consumer contracts. Review public exports, CSS entry points, peer dependencies, and accessible behavior before changing a primitive.
• [DESIGN-CHANGELOG-001] MUST — Lead a changeset with its entry. Write the changelog entry as a changeset's first paragraph — one sentence, under 160 characters — and put the reasoning below a blank line, where the documentation site folds it away.
• [DESIGN-I18N-001] MUST — Ship a changeset's Chinese with it. Translate a changeset's sentences into apps/docs/src/i18n/changelog.ts in the pull request that writes the changeset, not in the release that publishes it.
• [DESIGN-TEST-001] MUST — Run package gates. Use pnpm lint, pnpm typecheck, pnpm test, and pnpm build for affected code and output.
• [DESIGN-SYNC-001] MUST — Keep Claude Design sync interactive. Use the documented skill only after local verification; do not move credentials or interactive approval into CI.